How to integrate with Asterisk
The Asterisk integration functionality has a separate license in bpm’online. Form a license request, send it to our service team, upload the received license file into the system and distribute the licenses between the users.
Note
See more details about licensing in the “Software licensing” and “License distribution” articles.
The integration is only possible if complete preliminary Asterisk setup was performed by the phone integration administrator.
Preparing Asterisk
The AMI (Asterisk Manager Interface) interface is used to interact with Asterisk. Use AMI to connect to Asterisk servers, configure and manage client programs.
1.Create an AMI user for bpm'online, specify the user's parameters in the “manager.conf” file, for example:
[terrasoft]
secret = terrasoft
deny=0.0.0.0/0.0.0.0
permit=0.0.0.0/0.0.0.0
read = system,call,log,verbose,command,agent,user,originate
write = system,call,log,verbose,command,agent,user,originate
Note
The “deny” and “permit” values should be replaced with the corresponding addresses.
2.Check the parking feature activity and the “features.conf” file parameters, for example:
parkext => 700
parkpos => 701-720
context => parkedcalls
parkingtime => 45
Attention!
The "parkingtime" value determines the maximum time a call can be on hold. Upon the expiry of this time the subscriber will resume the conversation with the agent. The “parkingtime” value should be sufficiently long to avoid early call return.
Setting up bpm’online messaging service
The messaging service enables the use of AMI protocols to connect to Asterisk and distribute call events between bpm’online users.
1.Contact bpm'online support at support@bpmonline.com to receive installation files. Run the received BPMonline Messaging Service Install.msi file on the computer that will be used as the message exchange server and proceed with the installation.
2.Specify the following parameters for Asterisk connector in the “Terrasoft.Messaging.Service.exe.config” configuration file:
<asterisk filePath="" url="Asterisk_name_or_server_address" port="Asterisk_server_port”. userName="Asterisk login" secret="Asterisk password" originateContext="Outbound context” parkingLotContext="Parking context" autoPauseOnCommutationStart="true” queueExtensionFormat="Local/{0}@from-queue/n" asyncOriginate="true" sendRingStartedOnRingingState="true" traceQueuesState="false" packetInfoConfig="Additional packages values to handle within the configuration" />
See the list of Asterisk connector parameters in the following table.
| Parameter caption | Parameter assignment |
| FilePath | Use this parameter for diagnostics of the system. It allows to repeat a set of events from the file. The default value should be empty. |
| URL | Asterisk server IP address parameter. |
| Port | AMI protocol port. By default, “5038”. |
| OriginateContext | The command is used to initialize the call from bpm’online phone number. The parameter contains the caption of the context from which the call will be made to the user phone number. The default value for FreePBX is “from-internal” |
| parkingLotContext | The context for call initialization to receive parking line. The default value is “originateContext”. |
| AutoPauseOnCommutationStart | The checkbox is used for the correct work with Asterisk queues. If the checkbox is selected, the system will put the agent on a pause in all queues after answering the call. The feature is used to avoid the second call during the handling of the first one and/or putting the first call on hold. |
| queueExtensionFormat | The call channel format while receiving the call from the queue. If using LocalChannel, the default value in FreePBX is “Local/{0}@from-queue”. |
| sendRingStartedOnRingingState | The checkbox stands for the correct handling of the call from the queue. If this checkbox is selected, the system will display the call after receiving the “NewState” event with the Ringing parameter by AMI. The default value is “On”. |
| traceQueuesState | This setting is used to define the agent's status in the queues. If the agent receives the second call from the queue while handling the first one in bpm’online, it is used for debugging. Information about the status of agents is being written to the log file of the connector. The default value is “Off”. |
Configuration example:
<asterisk filePath=" "url="10.0.15.185" port="5038"
userName="bpm" secret="bpm" originateContext="from-internal"
parkingLotContext="from-internal" autoPauseOnCommutationStart="true"
queueExtensionFormat="Local/{0}@from-queue/n" asyncOriginate="true"
sendRingStartedOnRingingState="true" traceQueuesState="false"
packetInfoConfig=""/>
Setting up message exchange library
Message exchange library selection and setup is performed once by the system administrator. To set up the message exchange library:
1.Open the system designer by clicking the 
button in the top right corner of the application window.
2.Click the [System settings] link in the [System setup] block (Fig. 1).
Fig. 1 Opening the [System settings] section
3.In the [Default messages exchange library] system setting, set the default value to “Phone integration library based on Asterisk (AMI) protocol”.
4.In the [Message exchange server] system setting, select the connection parameters of the system messages service. In the [Default value] field, specify the message exchange network address in the following format: “ws://0.0.0.0:2013”, if your website is available by the http protocol, or “wss://0.0.0.0:2013”, if your website is available by the https protocol, where:
•“0.0.0.0” – IP address that your bpm’online users use to access your message exchange server.
•“2013” – the port used by default for connecting to the messaging service. You can change the port number in the “Terrasoft.Messaging.Service.exe.config” file.
Note
If your website is available by https and secure (wws) connection is used for websockets, you will need to install a security certificate on the message exchange server and specify it in the configuration files of the message service. For more information about the setup process, contact bpm'online's technical support at support@bpmonline.com.
Setting Asterisk parameters
These settings should be applied to every bpm’online user who received Asterisk integration license. To do this:
1.Open the user profile page by clicking the [Profile] image button on the main page of the application.
2.Click the [Call Center parameters setup] button.
3.On the displayed page, populate the required fields:
a.[Disable Contact Centre integration] – this checkbox allows you to disable bpm’online integration with the phone integration. The call button will not be displayed on the communication panel of the application.
b.[Number] – Asterisk user line number. It matches the phone number by default. For example, to track the SIP/305 user line, specify the “305” value, and to track the SIP/office line, specify the “office” value.
c.[Outgoing call context] – specify the outgoing call context if it differs from the system outgoing call context specified in the “Terrasoft.Messaging.Service.exe.config” file for this particular user.
d.[Enable debugging] – the checkbox allows you to display troubleshooting information within the browser console. This troubleshooting information can be used when the phone integration runs into problems and the customer addresses the service team.
4.Click the [Save] button on the page.
5.Refresh the browser page to apply the changes.
See also
•How to configure WSS connection for the phone service
