Introduction

Asterisk is an OpenSource software for telephony. This software is often used to run IP PBX systems inside companies, combined with an IP phone for each employee and SIP trunks on xDSL or fiber links or traditionnal ISDN lines to access the public telephone network. Asterisk is available under the GNU General Public Licence and is edited by the American company Digium. If you want to know more about Asterisk, please read its Wikipedia page.

Description of the connector

The Odoo-Asterisk connector has three main features. The first main feature is click2dial. Here is how it works :

1. In Odoo, in a form view that has a phone/mobile field, the user clicks on the phone number (on v10 and lower, he has to click on the dial button next to the phone number field).
2. Asterisk makes the user’s phone ring.
3. The user answers his own phone (if he doesn’t, the process stops here).
4. Asterisk dials the phone number found in Odoo in place of the user.
5. If the remote party answers, the user can talk to his correspondent.

The second main feature is : it adds the ability to show the name of the correspondant on incoming and outgoing phone calls if the phone number is present in the Partners, Leads or Employees of Odoo. Here is how it works :

1. On incoming and outgoing phone calls, the Asterisk dialplan executes a script.
2. This script will make an XML-RPC or JSON-RPC request to the Odoo server to try to find the name of the person corresponding to the phone number of the remote party.
3. If it finds the name, it updates the information on the call, so as to be presented on the SIP phone of the user.

The third main feature is : the ability to get the partner/lead/employee/candidate corresponding to the calling party in one click. Here is how it works :

1. Someone calls you. Before or after taking the call, you click on the phone logo at the top right of the screen, next to your username : Odoo sends a query to the Asterisk Manager Interface to get a list of the current phone calls (ringing or on conversation).
2. If it finds a phone call involving the user’s phone, it gets the phone number of the calling party
3. It searches the phone number of the calling party in the Partners of Odoo. If a record matches, it shows the name of the related Partner and proposes to open it, or open its related sale orders or invoices. If no record matches, it proposes to create a new contact with the presented phone number as ‘Phone’ or ‘Mobile’ number or update an existing Partner.

Other possibility (independant of Asterisk, using the base_phone_popup module) :

1. When an incoming call arrives, Asterisk executes an AGI script with the information about the logins of the Odoo users that should receive the pop-up. This AGI script sends an XML-RPC or JSON-RPC request to Odoo.
2. Odoo receives the request with the logins of the Odoo users that should be notified and the phone number of the calling party. If the phone number is available in Odoo, Odoo shows a notification pop-up that contains a link to the form view of the calling partner/lead/employee/candidate (or, if the phone number is unknown, the link points to the Number not found wizard).

Akretion service offering

Deploying the Asterisk-Odoo connector require to have expertise on both Odoo and Asterisk. As the ERP and IP PBX systems are two critical components for your company, you may prefer to delegate the installation and configuration of the connector to an experienced consultant.

Being the author of the Asterisk-Odoo connector, Akretion is the best option to find this expertise. Akretion proposes a service package for the Asterisk-Odoo connector which includes :

• if necessary, an update of the code of the modules of the Asterisk-Odoo modules to make it work on the version of Odoo that you are using,
• if necessary, an update of the code of the Asterisk-side scripts to make them work on the version of Asterisk that you are using,
• the installation and configuration of the relevant modules,
• the update of the configuration of your existing Asterisk IPBX to make it work with the Odoo-Asterisk connector,
• a brieffing on the use of the module,
• technical support via email and a bug-fix warranty during a period of 2 months starting from the date of installation of the module. This warranty is a bug-fix warranty on bugs that alter the behavior of the Asterisk-Odoo connector as described in this document. This warranty requires a remote access to the Odoo and Asterisk servers, or the customer should make available to Akretion a mean to reproduce the issue at Akretion’s office.

This service package is proposed at a price of 400 EUR without taxes.

This service package doesn’t include :

• enhancement requests,
• additionnal Asterisk setup and configuration that is not necessary to make the Odoo-Asterisk connector work,
• technical support and bug-fix warranty after the period of 2 months starting from the date of installation of the module,
• technical support and bug-fix warranty on Odoo modules that are not part of the Odoo-Asterisk connector or on Asterisk-side scripts that are not part of the Odoo-Asterisk connector.

Installation of the modules

The Odoo-Asterisk connector is made of several modules ; some of them are independant from Asterisk (all the modules that don’t have asterisk in their name are independant from Asterisk : base_phone, base_phone_popup, crm_phone, hr_phone, etc…) and one is specific to Asterisk (asterisk_click2dial).

These modules should be installed on Odoo just like any Odoo module. The source code of the module is available on the connector-telephony project of the Odoo Community Association (OCA) on github. Make sure to select the right branch depending on your version of Odoo.

These modules require two additional Python libraries : phonenumbers and py-Asterisk. To install these libraries, run :

% sudo pip install phonenumbers

% sudo pip install py-Asterisk

The pip command is the official tool to install Python libraries. If you don’t have this tool on your system, install the corresponding package (package python-pip on Debian/Ubuntu systems).

Setup the click2dial feature

Configuration of Asterisk

For the click2dial feature, Odoo will communicate with Asterisk through the Asterisk Manager Interface (AMI).

So the first step is to configure AMI :

• create a new AMI account for Odoo
• configure AMI to accept requests from Odoo for click2dial.

The configuration file of AMI is /etc/asterisk/manager.conf (depending on your Linux distribution, the directory may be different). Here is a sample configuration file with my comments inline :

; manager.conf file for the Asterisk Manager Interface (AMI)

; It starts with the “general” section first

[general]

; You must enable the AMI feature

enabled=yes

; TCP Port on which AMI will listen

port = 5038

; I suppose Asterisk and Odoo are on two different machines,

; so you must bind AMI on 0.0.0.0

bindaddr = 0.0.0.0

; We don’t need to activate the HTTP AMI interface : the module uses the native interface

webenabled = no

; Then, we create an AMI account for Odoo

[click2dial] ; This is the AMI login

secret = mypassword ; This is the AMI password

; We deny AMI access for everybody

deny = 0.0.0.0/0.0.0.0

; We accept AMI access for Odoo server (192.168.0.42)

permit = 192.168.0.42/255.255.255.255

; We give the minimum access rights required for the click2dial feature

; For Asterisk 1.4.x, you need the “call” rights (for both click2dial and the 'open calling party' feature)

;read =

;write = call

; For Asterisk 1.6.x and 1.8.x, you need the “originate” rights (for click2dial)

; and the 'reporting' rights (for the 'open calling party' feature)

read =

write = originate,reporting

Warning : On older version of Asterisk, you needed to restart Asterisk (check that nobody is on the phone, because a restart of Asterisk will stop all ongoing phone calls). On newer version of Asterisk, just type manager reload in the Asterisk CLI.

Now check that you can access the AMI from the Odoo server :

% nc <asterisk_server_IP_address> 5038

It should display :

Asterisk Call Manager/<version of AMI>

Configure Odoo

Log on as administrator on Odoo.

Configure Asterisk server(s)

First, you must create one or several Asterisk servers. The click2dial module supports several Asterisk servers (for each Odoo user, you will configure on which Asterisk server he is connected).

Go to the menu Settings > Technical > Telephony > Asterisk Servers. Create one or several Asterisk servers. All the fields have a detailed contextual help, so you should be able to understand how to set each parameter by reading the help.

Some parameters require additional explanations :

• Alert-Info SIP header : you will find more explanations about it in the sections Quiet click2dial and Auto-answer on click2dial with Aastra IP phones below. You can leave it empty for now, it is not a problem.

Configure users

Go to the menu Settings > Users > Users. For each user that require the click2dial feature, you need to set some parameters that the asterisk_click2dial module has added in the Telephony tab :

• Asterisk channel type : the channel type of the phone of the user (if the user has a regular IP phone, select SIP)
• Resource name : this is the resource name for the channel type that you selected. If you channel type is SIP, the resource name is the name of the entity that you defined in /etc/asterisk/sip.conf. For example, if you have an entity defined with [alexis] in sip.conf, then the resource name is alexis (it also means that you use Dial(SIP/alexis) to call this user in your Asterisk dialplan). For SIP phones, the internal phone number is often used as resource name.
• Internal number : the internal phone number of the user
• Caller ID : this field is important. If you don’t know what a Caller ID is, you should read more documentation about Asterisk. In short, it has to do with the name and phone number presented to the remote party. When you call someone via click2dial, the callerid parameter for your IP phone defined in /etc/asterisk/sip.conf (if you have a SIP phone) will NOT be used ; the Caller ID field defined in Odoo will be used instead. You should use the same syntax for the Caller ID field in Odoo than for the callerid field in Asterisk, for example :

Alexis de Lattre <141981242>

• Alert-Info SIP header : this is the same parameter as for the Asterisk server, but user-specific. You can leave it empty for now.
• Variable : this parameter is for advanced Asterisk users only. Leave it empty for now.
• Propose to create a call in the CRM after a click2dial : this option is available only if you have installed the asterisk_click2dial_crm module ; it is activated by default. It can also be modified via the user’s preferences (this means that users can modify this option by themselves).
• Asterisk server : select the Asterisk server on which the IP phone of the user is registered. If your company only has one Asterisk server, you can leave this field empty : Odoo will use the only Asterisk server created in Odoo.

Quiet click2dial

Imagine you share the same workroom with other colleagues. When one of your colleagues makes a phone call, the workroom stays quiet until the conversation starts. Now, if the colleague uses the click2dial feature of Odoo, his phone will ring and bother everyone before the conversation even starts ! I think it’s an important drawback.

Hopefully, there is a solution to his : when Asterisk “calls” the user (before calling the remote party), he should tell the phone not to ring. In fact, when I say “tell the phone not to ring”, I mean “tell the phone to use a silent ring tone”. This is usually possible with SIP phones. In the SIP protocol, you can use the Alert-Info header to tell the phone to choose a particular ring tone. This feature is often called “distinctive ringing” or “priority alerting”. Most SIP phones support the Alert-Info header, but :

• the exact syntax of the content of the header may differ from one SIP phone manufacturer to another,
• the name of the ring tones may also differ from one SIP phone manufacturer to another.

I have tested this feature with two different phone manufacturers : Technicolor i.e. the new name of Thomson (ST2030 model, it probably works the same way with other models) and Aastra (6731i model, I am sure the other models work the same way). I give the details below ; if you have some experience with other phones, don’t hesitate to send me an email (alexis.delattre at akretion.com) and share your knowledge.

Technicolor ST2030 IP phones

I suppose you use TFTP to configure the phone. If you edit the default configuration file for system melodies which is called Tone-RG.txt, you will see a ring tone Silent defined like this :

Silent:d=32,o=5,b=160:8P,2D

With this configuration, it is a “quiet” ring tone, but not a fully silent one. To make it a fully silent, change the definition of this ring tone to :

Silent:d=32,o=5,b=160:P

Note : for the changes to take effect, don’t forget to change the name of the ring tone file and update the filename in the parameter system_melodies of the <MAC_address>.inf file.

Then, in Odoo, in the configuration of the Asterisk server, you should give the following value to the the Alert-info SIP header :

info=<Silent>

Aastra IP phones

According to the Aastra documentation, a Silent ring tone exists, but it can’t be used for distinctive ringing. I found a workaround for this : choose a ring tone that is not used but default, for example Bellcore-dr5 (which is a “quiet” ring tone, but not a fully silent one), and redefine it in the configuration file (aastra.cfg to change it for all Aastra phones, or <MAC_address>.cfg to change it only for one phone) :

bellcore cadence dr5: 0,-1

This will convert the ring tone Bellcore-dr5 to a fully silent ring tone.

Then, in the configuration of the Asterisk server in Odoo, you should give the following value to the Alert-info SIP header :

info=<Bellcore-dr5>

Note : if you have a mix of Aastra and Technicolor phones, you can either use the user-specific Alert-info SIP header which is available on the User’s form, or use the server-wide Alert-info SIP header parameter and rename the Silent ring tone of the Thechnicolor IP phone to Bellcore-dr5.

Auto-answer on click2dial with Aastra IP phones

If you want your Aastra IP phones (other IP phones also support this feature) to answer automatically on a click2dial, here is how to proceed.

First, you need to configure the *Incoming intercom calls" on your Aastra IP Phone. Here are the parameters that you should use in your Aastra configuration file :

sip allow auto answer: 1 # Allow auto-answer on incoming intercom calls
sip intercom warning tone: 1 # Activate warning tone on incoming intercom calls
sip intercom mute mic: 0 # Enable microphone on incoming intercom calls

Then, in the Alert-info SIP header, enter :

info=alert-autoanswer

If the Alert-info SIP header already has a value, note that you can put several values in this field if you separate them with ‘;’, for example :

info=<Bellcore-dr5>;info=alert-autoanswer

If you want the auto-answer to be user-specific, use the Alert-info SIP header of the user’s form ; if you want it to be for all the users of an Asterisk server, use the Alert-info SIP header of the Asterisk server form. When the Alert-info SIP header of the user’s form is set, the equivalent field on the server form is ignored.

Now, when you do a click2dial, your Aastra IP Phone will auto-answer the call and use the speaker by default.

Get the name of the calling party on incoming phone calls

Technical introduction

Here is a scenario which explains how the feature works :

1. On incoming phone calls, the Asterisk dialplan executes an AGI set_name_incoming_timeout.sh
2. The set_name_incoming_timeout.sh script calls the set_name_agi.py script with a short timeout.
3. The set_name_agi.py script will make an XML-RPC or JSON-RPC request on the Odoo server to try to find the name of the person corresponding to the phone number presented by the calling party.
4. If it finds the name in Odoo, the name is used as CallerID name for the call, so that users can see the name on the screen of their IP phone. If it doesn’t find any match in Odoo, it can geolocalize the phone number and display the country and city name as CallerID (if you active a specific option).

Setup on the Odoo side

I recommend to create a new user on Odoo ; for example, we will call it asterisk. This asterisk user will be dedicated to this feature and will only have the minimum access rights required to use the feature. For that, add this asterisk user to the Asterisk CallerID group (this group only has the minimum access rights required to use the feature).

Setup on the Asterisk side

First, make sure that you can reach the HTTP or HTTPS port of Odoo from the Asterisk server ; if it doesn’t work, check your network settings and firewalling rules.

Second, check that the shell command timeout is available on your Asterisk server :

• under Debian Lenny or lower and Ubuntu Lucid 10.04 or lower, you have to install the timeout package,
• under Debian Squeeze or higher and Ubuntu Maverick 10.10 or higher, this shell command is provided by the package coreutils which is installed by default.

Then, copy the two files set_name_agi.py and set_name_incoming_timeout.sh in the directory /usr/local/bin/ of your Asterisk server. Make sure that the two scripts have execution rights. You will find below some details about the two scripts.

Install the pyst2 library:

sudo pip install pyst2

The script set_name_agi.py is written in Python and it’s the one which “makes the job” :

• it receives on its standard input the parameters given by Asterisk, in particular the phone number,
• it sends an XML-RPC or JSON-RPC request to Odoo to ask if it can find the phone number in the Partner addresses,
• it writes on its standard output some instructions for Asterisk, in particular to change the CallerID name.

This script has some options:

• the DNS or IP address of the Odoo server,
• the port of the Odoo server,
• an option to use XML-RPC, JSON-RPC or XML-RPC over SSL,
• the name of the Odoo database to use,
• the ID of the Odoo user (in our example, write the ID of the user asterisk that we created in the previous section) if you use XML-RPC ; the login of the Odoo user if you use JSON-RPC,
• it’s password,

Run set_name_agi.py -h to have the syntax of these options.

Then, there is the script set_name_incoming_timeout.sh which is a one-line shell script. This is the script that is called from the Asterisk dialplan and that calls the script set_name_agi.py with the appropriate options. Why do we need this intermediate script ? This intermediate script calls the script set_name_agi.py with a short timeout of 2 seconds by default ; if the script set_name_agi.py has not finish it’s job after 2 seconds, it will be killed. It is important to set such a timeout because the script will be called by Asterisk upon each incoming phone call ; it the script get stucks, the phone call will also get stucks and you will miss the call !

Edit the script set_name_incoming_timeout.sh and put the right options.

Modify the Asterisk dialplan to call the script upon the reception of an external phone call. If you have written the Asterisk dialplan yourself, edit the dialplan (usually /etc/asterisk/extensions.conf) and, in the context dedicated to the reception of external phone calls, insert an extension that will execute the AGI function with the location of the script (/usr/local/bin/set_name_incoming_timeout.sh) as parameter. Of course, this extension must be placed before the Dial() function which rings the IP phone of the user. For example :

[from-extern]
exten = _141981242,1,AGI(/usr/local/bin/set_name_incoming_timeout.sh)
same = n,Dial(SIP/10, 30)
same = n,141981242,n,Answer()
same = n,Voicemail(10@default,u)
same = n,Hangup()

Then, reload the Asterisk diaplan :

asterisk*CLI> extensions reload

If you haven’t written the Asterisk dialplan yourself, which is the case of users which use FreePBX or Wazo or any other administration interface for Asterisk, you need to figure out how to insert the extension with the AGI script in the dialplan functions which manage the reception of external calls. If you need help for this, please consider Akretion’s service offering.

You are now ready to receive your first phone call with CallerID name lookup in Odoo !

It is also possible to do the same thing for outgoing calls ; the setup is quite similar and you need to use the script set_name_outgoing_timeout.sh and a few additionnal lines in the dialplan. You will find an example in the comments at the beginning of the script set_name_agi.py.

Setup the ‘open calling party’ feature

Setup

This feature requires the same configuration as the click2dial feature, which is explained above.

Warning : if you have already deployed the click2dial feature and you upgraded the module to get the new open calling party feature, you should update your /etc/asterisk/manager.conf file to add some write priviledges to the AMI user, cf the click2dial section above.

Use the ‘open calling party’ feature

Here is a typical scenario :

1. Your phone rings.
2. You click on the phone logo at the top right of the screen.
3. Odoo sends a Status request to the Asterisk Manager Interface (AMI) to get the list of all the current phone calls. It will get the first call that involves your phone number and it retrieves the presented phone number.
4. Odoo searches the presented phone on partners/leads/employee/candidate/event participants. If it finds a match, it opens the form view of the partner/lead/employee/candidate/event participant.

If it doesn’t find a match, it opens a pop-up that shows the presented phone number and proposes to create a new partner/lead or update an existing partner/lead.

Troubleshooting

If you have some issues with the module :

• start odoo-bin with the command line option --log-level=debug : you will get usefull messages about the phone number reformating process and the connection to the Asterisk Manager Interface.
• also check logs on the Asterisk side : on your Asterisk server, run :
  % asterisk -rvvvvvvvvvvvv
  
• if the Odoo server and Asterisk don’t communicate, use tools such as tcpdump or wireshark to check the network traffic between the two machines. Run for example :
  % tcpdump -n -i eth0 -A -s 0 port 5038
  
• for the feature “CallerID name lookup in Odoo on incoming phone calls”, you can get more logs about the execution of the AGI script by running this command in the Asterisk console :
  asterisk*CLI> agi set debug on
  
  To disable it :
  asterisk*CLI> agi set debug off