How to integrate with Asterisk

In Creatio, the Asterisk integration functionality requires a separate license. You need to generate a license request, send it to our service team, upload the received license file into the system and finally, 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 Creatio, 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.

Main integration steps

After you prepare the Asterisk telephony for integration, perform the following steps:

• Set up Creatio Messaging Service. Read more >>>

• Set up message exchange library. Read more >>>

• Set the Asterisk parameters. Read more >>>

Attention

If you set up the telephony for a development environment application, locate Creatio Messaging Service on a separate node instead of the Creatio application server. To ensure the fault tolerance of your phone integration, we recommend setting up at least two nodes with Creatio Messaging Service, as well as a balancer that would redirect users in case of lost connection with one of the nodes.

Setting up Creatio messaging service

The messaging service enables the use of AMI protocols to connect to Asterisk and distribute call events between Creatio users. Some of the settings differ depending on the platform that he Asterisk telephony service is deployed on – NET Framework or .NET Core.

Set up Creatio messaging service on the .NET Framework platform

1.Contact Creatio support to receive the setup files. Run the Creatio Messaging Service Install.msi file (received from Creatio support) on the computer that will be used as the message exchange server and proceed with the installation.

Attention

.NET Framework of version 4.7.2 or higher should be installed on the server where you configure the Creatio Messaging Service.

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" protocol="The_protocol_used–SIP/_or_PJSIP/" packetInfoConfig="Additional_packages_values_to_handle_within_the_configuration" />

See the list of Asterisk connector parameters in the following table.

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"
protocol="SIP/" packetInfoConfig=""/>

Set up Creatio messaging service on the .NET Core platform

Attention

You can set up Messaging Host on the .NET Core platform for Creatio version 7.16.3 and up.

1.Install Docker. Installing Docker on Linux platforms is covered in the Docker guide. Run the “docker --version” command on Linux machine to verify the installed Docker version.

2.Install Docker Compose. Installing Docker Compose for Linux OS is covered in the Docker guide. Run the “docker-compose --version” command on Linux machine to verify the installed Docker Compose version.

3.Install an set up the Docker Compose components. The container of the messaging service is deployed via the Docker Compose utility. Download and unzip the archive with the configuration files and scripts to a custom directory, for example, /opt/messaging.host. Download the archive

Note

The configuration files contain all necessary default settings for a Linux based server.

The archive structure of the configuration files and scripts:

/etc/
...\appsettings.json — service cofiguration
...\nlog.config — setting up the service logging level
Docker-compose.yml – the “Docker Compose” utility configuration
.env – the file containing environment variables for running the components

4.Using the Linux terminal, go to the /docker-compose catalog of the unzipped archive, for example, /opt/messaging.host/docker-compose.

5.Run the “sudo docker-compose pull” command in the terminal. Wait until the download of the required service component images from the Docker Hub is complete.

Attention

If the server Internet access is restricted, download the needed images manually to a machine with free access (see the docker-compose.yml configuration file) and transfer the images as files to the target machine using the  sudo docker export and sudo docker import commands.

6.Specify the following parameters for Asterisk connector in the “etc/appsettings.json” configuration file:

{

   "url": "Asterisk_server_name_or_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",
   "protocol": "The used protocol type – SIP/ or PJSIP/",
   "packetInfoConfig": "Additional package parameters for processing in configuration",
   "filePath": ""
}

7.Run the sudo docker-compose up -d command to launch the service. A “logs” folder will be created in the current catalog.

See the list of Asterisk connector parameters in the following table.

Configuration example:

"asterisk": {
   "url": "Asterisk_server_name_or_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",
   "protocol": "The used protocol type – SIP/ or PJSIP/",
   "packetInfoConfig": "Additional package parameters for processing in configuration",
   "filePath": ""
}

Setting up message exchange library

Message exchange library selection and setup is performed once by the system administrator. Some of the settings differ depending on the platform that he Asterisk telephony service is deployed on – NET Framework or .NET Core.

Set up library on the .NET Framework platorm

1.Open the system designer by clicking 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://[server]:2013” for sites accessible via HTTP, or “wss://[server]:2013” for sites accessible via HTTPS, where:

•[server] – domain name of the server that hosts the message exchange service. Using IP addresses or “localhost” is not recommended.

•“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. Using “localhost” is not recommended, as it may cause errors when connecting to the phone integration server. When using a wss connection, make sure that server address matches the address in the SSL certificate.

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 Creatio technical support at support@creatio.com.

Set up library on the .NET Core platorm

Attention

You can set up Messaging Host on the .NET Core platform for Creatio version 7.16.3 and up.

1.Open the system designer by clicking in the top right corner of the application window.

2.Click the [System settings] link in the [System setup] block (Fig. 2).

Fig. 2 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 message service. In the [Default value] field, specify the message exchange network address in the following format: “http://[server]:2013” for sites accessible via HTTP, or “http://[server]:2014” for sites accessible via HTTPS, where:

•[server] – domain name of the server that hosts the message exchange service. Using IP addresses or “localhost” is not recommended.

•“2013 or 2014” – the port used by default for connecting to the messaging service. You can change the port number in the “docker-compose.yml” configuration file. Using “localhost” is not recommended, as it may cause errors when connecting to the phone integration server. When using a https connection, make sure that server address matches the address in the SSL certificate.

Note

If your website is available by HTTPS and secure connection is used for WebSockets, you will need to install a security certificate on the message exchange server and specify it in the docker-compose configuration. For more information about the setup process, contact Creatio technical support at support@creatio.com.

Setting Asterisk parameters

These settings should be applied to every Creatio 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 Creatio 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.

Attention

A separate line is used for each user. It is not recommended to specify the same line for several users, as it may cause errors.

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 [Save].

5.Refresh the browser page to apply the changes.

See also

•Software licensing

•License distribution

•Configure WSS connection for the phone service

•Creatio phone integration FAQ

• Asterisk phone integration (development guide)