Odoo Asterisk VOIP connector

\

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. First, it adds a dial button next to the phone number fields in Odoo form views so that your users can directly dial a phone number through Asterisk. This feature is usually known as click2dial. Here is how it works :

1. In Odoo, the user clicks on the dial button next to a phone number field in the form view.

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 corresponding to the calling party in one click (module asterisk_click2dial) or in zero-click (module base_phone_popup). Here is how it works for the one click pop-up :

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.

Here is how it works for the zero-click pop-up :

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 opens the related form view via a Websocket.

The zero-click pop-up requires a very specific configuration with an HTTP proxy that support WebSockets, a web browser that support Websockets, etc…

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 successor of easy_install and 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 OpenERP 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 : simply reloading Asterisk is not enough to activate the AMI ; you need to restart Asterisk (check that nobody is on the phone, because a restart of Asterisk will stop all ongoing phone calls).

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

% telnet <asterisk_server_IP_address> 5038

It should display :

Connected to <asterisk_server_IP_address>.
Escape character is '^]'.
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.

• the different prefixes : you will find more explanations about it in the section How phone numbers are reformated below.

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 OpenERP 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.

That’s it, the configuration is finished, you can start playing with click2dial !

How phone numbers are reformated

This diagram explains how phone numbers are managed by the asterisk_click2dial module.

In the diagram, the two examples (ex1, ex2 and ex3) are based on the following configuration :

• Out prefix : 0

• National prefix : 0

• International prefix : 00

• My country prefix : 33

Use the click2dial feature

In Odoo, go to any menu that give you access to Partners and open a partner that you want to call. In the General tab, select the Partner contact that you want to call. Next to the Phone and Mobile fields, you should see a Dial button.

Important : the phone number in Odoo should be in international format, for example : +33 1 41 98 12 42

This is the same format that you must use in your mobile phone’s directory when you want to be able to call a number saved in your phone’s directory when you travel abroad. For example, check this Nokia user manual \ page 19, section Make calls, look at the tip.

If the phone number is not in the international format, you will get an error message when you click on the Dial button, unless you activated the option Allow national formats ? for this the Asterisk server.

Here is the complete usage scenario pf the click2dial feature :

1. Click on the Dial button next to the phone number you want to dial.

2. Odoo reformats the phone number using the different prefixes defined for this Asterisk server. Then Odoo connects to the Asterisk Manager Interface and sends a request.

3. Asterisk makes the user’s phone ring.

4. The user answers his own phone. If he doesn’t answer his phone, the process stops here, the next steps are not executed.

5. Asterisk dials the phone number that has been reformated and, immediately after dialing, connects the user’s phone to the call (the user hears the call waiting tones, just like if he had dialed the number himself).

6. The user is in full control of the call.

7. If you haven’t disabled the option Propose to create a call in the CRM after a click2dial on the user form or via the user’s preferences, you will get a pop-up that proposes to create a phone call in the CRM :

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 OpenERP, 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=;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 get_cid_name_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

Make sure that you have a recent version of the asterisk_click2dial module with the function get_name_from_phone_number in the file asterisk_click2dial.py.

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 OpenERP 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.

Eventually, if you are interested by the geolocalisation feature, install the Python library phonenumbers on your Asterisk server :

  % sudo pip install phonenumbers

This library contains a database of phone prefixes and their corresponding region/city names for about 55 000 phone prefixes of the world (cf the file phonenumbers/geodata/\_\_init\_\_.py of the library).

First, 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, in particular the information to connect to Odoo and the optional geolocalisation feature:

• 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),

• it’s password,

• if you enable the geolocalisation option, you should provide your country (required to parse presented phone numbers correctly) and the language in which you want the country and city name to be displayed.

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.

Test the script with a phone number that is present in the Partner addresses of OpenERP :

# echo \"agi_callerid:141981242\"| /usr/local/bin/set_name_incoming_timeout.sh
Full AGI environnement :
agi_callerid = 141981242
VERBOSE \"CallerID number = 141981242\"  \   phone number sent to OpenERP = 141981242
VERBOSE \"Starting XML-RPC request on OpenERP localhost:8069\"
VERBOSE \"End of XML-RPC request on OpenERP\"
VERBOSE \"CallerID Name = Alexis de Lattre\"
SET CALLERID \"Alexis de Lattre\" <141981242>

The script outputs some debug information on stderr and some instructions to Odoo on stdout. In this example, the instructions to Odoo are the lines which start with VERBOSE or SET CALLERID. The important line is the last line which has the SET CALLERID instruction : it will tell Asterisk to replace the CallerID of the incoming call by the one given after the instruction.

If the phone number is not found in the Partner addresses of Odoo and you have enabled the geolocalisation option, the output would be :

# echo \"agi_callerid:0141931242\"| set_name_incoming_timeout.sh
full AGI environnement :
agi_callerid = 0141931242
stdout encoding = UTF-8
VERBOSE \"CallerID number = 0141931242\"
phone number sent to OpenERP = 141931242
VERBOSE \"Starting clear XML-RPC request on OpenERP 192.168.0.10:8069\"
VERBOSE \"End of XML-RPC request on OpenERP\"
VERBOSE \"Phone number not found in OpenERP\"
VERBOSE \"Trying to geolocate with country FR and lang fr\"
VERBOSE \"CallerID Name = France Vincennes\"
SET CALLERID \"France Vincennes\"<0141931242>

If you haven’t enabled the geolocalisation option, the last line will be :

SET CALLERID \"Not in Odoo\" <141981242>

You can personnalize the string “Not in Odoo” by editing the script set_name_agi.py.

If the test of the script is successfull, you can move on to the last step : 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)  \   exten => _141981242,n,Dial(SIP/10, 30)
exten => _141981242,n,Answer()  \   exten => _141981242,n,Voicemail(10@default,u)
exten => _141981242,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 Xivo 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

The ‘open calling party’ feature is currently only available for OpenERP 6.1 (backporting it to older versions of OpenERP should be easy).

Here is a typical scenario :

1. Your phone rings.

2. Before or after picking up the phone, go to the menu Sales > Address Book and you double-click on Open calling partner.

3. OpenERP 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. OpenERP searches the presented phone number in the Phone and Mobile fields of the Partner addresses of OpenERP (for this, it uses the same code as the Get the name of the calling party on incoming phone calls feature). If it finds a match, it opens a pop-up that shows the presented phone number, the name of the corresponding Partner address and the name of the corresponding Partner :

You now have several options corresponding to the buttons in the pop-up :

\ * open the form view of the Partner, * open the list view of the sale orders related to the Partner, * open the list view of the invoices related to the Partner, * if you have the asterisk_click2dial_crm module, it also proposes to create a phone call in the CRM.

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

Troubleshooting

If you have some issues with the module :

• start openerp-server 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 OpenERP 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 OpenERP 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