To set up an Asterisk integration, take the following steps:
- Prepare Asterisk for integration. Read more >>>
- Set up Creatio Messaging Service. Read more >>>
- Set up the message exchange library. Read more >>>
- Set up the Asterisk parameters. Read more >>>
In Creatio, the Asterisk integration functionality requires a separate license. You need to generate a license request, send it to our support team, upload the received license file into the system, and distribute the licenses among users. Learn more in separate articles: Creatio licensing and Manage user licenses.
The integration is only possible if complete preliminary Asterisk setup was performed by the phone integration administrator.
1. Prepare Asterisk for integration
The AMI (Asterisk Manager Interface) interface interacts with Asterisk. Use AMI to connect to Asterisk servers, configure and manage client programs.
To prepare Asterisk for integration, create an AMI user for Creatio by specifying their parameters in the manager.conf file, for example:
Replace the deny and permit values with the corresponding addresses.
2. Set up Creatio Messaging Service (formerly Terrasoft Messaging Service)
The messaging service lets you connect Creatio to Asterisk via AMI protocol and distribute call events between Creatio users. Some of the settings differ depending on the platform on which the Asterisk telephony service is deployed: .NET Framework or .NET Core or .NET 6.
Set up Creatio Messaging Service on .NET Framework
-
Before installing the Creatio Messaging Service (CMS), make sure that your computer runtime environment meets the software requirements:
- a .NET Framework package version 4.7.2 or later on the server where you are going to install Creatio Messaging Service
- at least 2 Gb of RAM and 20 Gb of free drive space
-
Contact Creatio support to receive the messaging service installation files or download the files via the URL: Download the archive. Unpack the archive to a folder to ensure a smooth installation. If you run the installation directly from the archive, the archiver application might interfere with the install wizard.
- Run the Creatio Messaging Service Install.msi file on the machine intended as the message exchange server and proceed with the installation.
- Make sure that the TerrasoftMessagingService service is running in the Windows Services application. If the TerrasoftMessagingService service is not running, start it manually.
-
Open the folder that contains the service files: ~\Terrasoft Messaging Service. Specify the following parameters for Asterisk connector in the Terrasoft.Messaging.Service.exe.config configuration file:
See the index of Asterisk connector parameters in the following table:
Parameter caption Parameter function filePath Use the parameter for system diagnostics. It lets you repeat a set of events from the pre-configured scenario file. The default value must be empty. url The IP address of the Asterisk server. port AMI protocol port. By default, 5038. originateContext Initiates a call to a phone number from Creatio. Contains the name of the context from which to call the user phone number. The default value for FreePBX is from-internal. autoPauseOnCommutationStart Ensures Asterisk queues work as intended. If enabled, Creatio puts the agent on a pause in all queues after they answer a call. Required to avoid the agent getting a second call while handling the first call or putting the first call on hold. queueExtensionFormat The format that determines the call channel while receiving calls from the queue. The default value for LocalChannel in FreePBX is Local/{0}@from-queue. sendRingStartedOnRingingState Ensures the call retrieval from the queue is handled correctly. If you select the checkbox, Creatio displays the call for the user after receiving the NewState AMI event that has the Ringing parameter. By default, “On.” traceQueuesState Diagnoses the agent status in the queue. Use the parameter to debug the queue if the agent receives a second call from the queue while handling the first call in Creatio. Agent status data is written to the connector log file. By default, “Off.” protocol The protocol type: SIP or PJSIP. Contact your PBX administrator to find out the needed protocol type. - Restart the CMS and test the phone integration. The connection to Asterisk is established on CMS startup but packet handling begins after an agent goes online.
Set up Creatio Messaging Service on .NET Core or .NET 6
-
Install Docker. To install Docker on Linux, follow the guide in the Docker documentation. To check the installed Docker version, run the following command at the Linux terminal:
-
Install Docker Compose. To install Docker Compose on Linux, follow the guide in the Docker documentation. To check the installed Docker Compose version, run the following command at the Linux terminal:
-
Install and set up the Docker Compose components. Deploy the container of the messaging service via the Docker Compose utility. Download the archive via the following link: Download the archive. Unpack the archive that contains the configuration files and scripts to any directory, for example, /opt/messaging.host.
The structure of the archive that contains the configuration files and scripts:
/etc/
...\appsettings.json: service configuration.
...\nlog.config: setup of the service logging level.
docker-compose.yml: configuration of the Docker Compose utility.
.env: environment variables to run the components.
- Use Linux terminal to go to the /docker-compose directory of the unpacked archive, for example, /opt/messaging.host/docker-compose.
-
Run the sudo docker-compose pull command at the terminal. Wait until the required service component images are downloaded from the Docker Hub completely.
-
Specify the following parameters for Asterisk connector in the etc/appsettings.json configuration file:
-
Run the sudo docker-compose up -d command to launch the service. A logs directory will be created in the current catalog.
See the list of Asterisk connector parameters in the following table:
Parameter caption Parameter function url The IP address of the Asterisk server. port AMI protocol port. By default, 5038. originateContext Initiates a call to a phone number from Creatio. Contains the name of the context from which to call the user phone number. The default value for FreePBX is from-internal. autoPauseOnCommutationStart Ensures Asterisk queues work as intended. If enabled, Creatio puts the agent on a pause in all queues after they answer a call. Required to avoid the agent getting a second call while handling the first call or putting the first call on hold. queueExtensionFormat The call channel format while receiving the call from the queue. The default value for LocalChannel in FreePBX is Local/{0}@from-queue. sendRingStartedOnRingingState Ensures the call retrieval from the queue is handled correctly. If you select the checkbox, Creatio displays the call for the user after receiving the NewState AMI event that has the Ringing parameter. By default, “On.” traceQueuesState Diagnoses the agent status in the queue. Use the parameter to debug the queue if the agent receives a second call from the queue while handling the first call in Creatio. Agent status data is written to the connector log file. The default value is “Off”. protocol The protocol type: SIP or PJSIP. Contact your PBX administrator to find out the needed protocol type. filePath Use the parameter for system diagnostics. It lets you repeat a set of events from the pre-configured scenario file. The default value must be empty. - Restart the CMS and test the phone integration. The connection to Asterisk is established on CMS startup but packet handling begins after an agent goes online.
3. Set up the 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 on which the Asterisk telephony service is deployed: NET Framework or .NET Core or .NET 6.
Set up the library on .NET Framework
- Open the System Designer, for example, by clicking
in the top right corner of the application.
- Click “System settings” in the “System setup” block.
- Open the “Default messages exchange library” (“SysMsgLib” code) system setting and set its default value to “Asterisk 13/16/18 (AMI) telephony integration library.”
-
Open the “Message exchange server” (“SysMsgServerNode” code) system setting and specify the connection parameters of the system messages service. Specify the network address of the message exchange server in the Default value field. Use the following format: “ws://server:2013” for sites served over HTTP or “wss://server:2013” for sites served over HTTPS, where:
- server is the domain name of the server that hosts the message exchange service. We do not recommend using IP addresses or “localhost.”
- 2013 is the default port to connect to the messaging service. You can change the port number in the Terrasoft.Messaging.Service.exe.config file. We do not recommend using “localhost” as it might 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.
Set up the library on .NET Core or .NET 6
- Open the System Designer, for example, by clicking
in the top right corner of the application.
- Click “System settings” in the “System setup” block.
- Open the “Default messages exchange library” (“SysMsgLib” code) system setting and set its default value to “Asterisk 13/16/18 (AMI) telephony integration library.”
-
Open the “Message exchange server” (“SysMsgServerNode” code) system setting and specify the connection parameters of the message service. Specify the network address of the message exchange server in the Default value field. Use the following format: “http://server:2013” for sites served over HTTP or “http://server:2014” for sites served over HTTPS, where:
- server is the domain name of the server that hosts the message exchange service. We do not recommend using IP addresses or “localhost.”
-
2013 or 2014 is the default port to connect to the messaging service. You can change the port number in the docker-compose.yml configuration file. We do not recommend using “localhost” as it might cause errors when connecting to the phone integration server. When using an HTTPS connection, make sure that server address matches the address in the SSL certificate.
4. Set up the Asterisk parameters
Apply the Asterisk parameters to every Creatio user who received Asterisk integration license. To do this:
- Open the user profile page by clicking the Profile image button on the main page of the application.
- Click the Call Center parameters setup button. This opens a page.
-
Fill out the following fields:
- Select the Disable Call Center integration checkbox to disable Creatio integration with the phone service. This hides the call button from the Creatio communication panel.
-
Specify the Asterisk user line number in the Number field. The line number matches the phone number by default. For example, to track the SIP/305 user line, specify 305, and to track the SIP/office line, specify the office.
- Specify the context of the outgoing call in the Outgoing call context field if the context for the user must differ from the system context specified in the Terrasoft.Messaging.Service.exe.config file.
- Select the Enable debugging checkbox to display troubleshooting information in the browser console. You can use the information if you encounter phone integration and customer contact issues.
- Click Save.
- Refresh the browser page to apply the changes.