Skip to main content
Version: 8.2

Set up integration with Asterisk

Level: intermediate

Follow these steps to set up an Asterisk integration with Creatio:

  1. Prepare Asterisk for integration. Read more >>>
  2. Set up Creatio Messaging Service. Read more >>>
  3. Set up the message exchange library. Read more >>>
  4. Set up the Asterisk parameters. Read more >>>

The Asterisk integration requires a separate license in Creatio. You need to generate a license request, send it to our support team, upload the received license file into Creatio, and distribute licenses among users. Learn more: Creatio licensing and Manage user licenses.

Integration is only possible after complete preliminary Asterisk setup by the phone integration administrator.

Important

When setting up telephony for a Creatio production environment, deploy Creatio Messaging Service on a separate node, not on the Creatio application server. For fault tolerance, we recommend configuring at least two nodes with Creatio Messaging Service and a balancer that redirects users if connection to one node is lost.

1. Prepare Asterisk for integration​

The AMI (Asterisk Manager Interface) facilitates interaction with Asterisk. Use AMI to connect to Asterisk servers and manage client programs.

To prepare Asterisk for integration, create an AMI user for Creatio by adding their parameters to the manager.conf file:

[creatio]
secret = creatio
deny=0.0.0.0/0.0.0.0
permit=0.0.0.0/0.0.0.0
read = call,agent,originate
write = call,agent,originate

Replace the deny and permit values with appropriate network addresses.

Important

While software phones or agent phones can place calls on hold, the Communication panel only handles call status changes. It displays when calls are placed on hold or resumed but cannot itself place calls on hold.

2. Set up Creatio Messaging Service (formerly Terrasoft Messaging Service)​

The messaging service lets you connect Creatio to Asterisk via AMI protocol and distributes call events between Creatio users. Some configuration settings differ depending on the Creatio platform: .NET Framework, .NET Core, or .NET 6.

Set up Creatio Messaging Service on .NET Framework​

  1. Before installing the Creatio Messaging Service (CMS), verify that your environment meets these requirements:

    • .NET Framework 4.7.2 or later on the server where you are going to install Creatio Messaging Service
    • at least 2 Gb RAM and 20 Gb free disk space

  2. Contact Creatio support for the messaging service installation files or download the archive. Unpack the archive to a folder for smooth installation rather than running directly from the archive.

    Important

    Deploy CMS on a server connected to both the Creatio application server and the PBX. Learn more: Telephony integration basics.

  3. Run Creatio Messaging Service Install.msi on your designated message exchange server and complete the installation.

  4. Verify that the TerrasoftMessagingService is running in Windows Services. Start it manually if not.

  5. Navigate to C:\Program Files (x86)\Terrasoft Messaging Service and configure Asterisk connector parameters in the Terrasoft.Messaging.Service.exe.config file:

    <asterisk filePath="" url="Asterisk server name or URL" port="Asterisk server port" userName="Asterisk login" secret="Asterisk password" originateContext="Outbound context" autoPauseOnCommutationStart="true" queueExtensionFormat="Local/{0}@from-queue/n" asyncOriginate="true" sendRingStartedOnRingingState="true" traceQueuesState="false" protocol="The protocol type used: SIP/ or PJSIP/" packetInfoConfig="Additional packet parameters to handle within the configuration" />

    See the index of Asterisk connector parameters in the following table:

    Parameter caption

    Parameter function

    filePath

    Used for system diagnostics to repeat a set of events from a pre-configured scenario file. Should be empty by default.

    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 context name for outbound calls. The default value for FreePBX is from-internal.

    autoPauseOnCommutationStart

    Ensures Asterisk queues work as intended. If enabled, Creatio puts the agent on pause in all queues after they answer a call. Prevents receiving additional calls while handling the first call or putting the first call on hold.

    queueExtensionFormat

    The format that determines the call channel for incoming calls from the queue. The default value for LocalChannel in FreePBX is Local/{0}@from-queue.

    sendRingStartedOnRingingState

    Ensures the retrieval of calls from the queue is handled correctly. If you select the checkbox, Creatio displays the calls to the user after receiving a 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. Logs agent status data to the connector log file. By default, "Off."

    protocol

    The protocol type: SIP or PJSIP. Contact your PBX administrator to determine the correct protocol type.

  6. Restart the CMS and test the phone integration. The connection to Asterisk is established on CMS startup, but packet handling begins only after an agent goes online.

note

Follow these instructions if you need to update Creatio Messaging Service.

Set up Creatio Messaging Service on .NET Core or .NET 6​

Important

Messaging Host (CMS) on .NET Core is supported in Creatio versions 7.16.3 through 8.0.8. Support for .NET Core 3.1 will be retired in Creatio version 8.0.9. We recommend migrating to .NET 6 when updating Creatio to version 8.0.8. Messaging Host on .NET 6 is supported in version 8.0.8 and later.

  1. Install Docker. To install Docker on Linux, follow the guide in the Docker documentation. Check the Docker version by running the following command in the Linux terminal:

    docker --version

  2. Install Docker Compose. To install Docker Compose on Linux, follow the guide in the Docker documentation. Check the installed Docker Compose version by running the following command in the Linux terminal:

    docker-compose --version

  3. 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 and extract it to a directory, for example, /opt/messaging.host.

    note

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

    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.

  4. Use Linux terminal to navigate to the docker-compose directory of the unpacked archive, for example, /opt/messaging.host/docker-compose.

  5. Run the sudo docker-compose pull command at the terminal. Wait until the required service component images are downloaded from the Docker Hub completely.

    Important

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

  6. Configure Asterisk connector parameters in the etc/appsettings.json file:

    {
        "url": "Asterisk server name or URL",
        "port": "Asterisk server port",
        "userName": "Asterisk login",
        "secret": "Asterisk password",
        "originateContext": "Outbound context",
        "autoPauseOnCommutationStart": "true",
        "queueExtensionFormat": "Local/{0}@from-queue/n",
        "asyncOriginate": "true",
        "sendRingStartedOnRingingState": "true",
        "traceQueuesState": "false",
        "protocol": "The protocol type used: SIP/ or PJSIP/",
        "packetInfoConfig": "Additional packet parameters to handle within the configuration",
        "filePath": ""
    }

  7. 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 context name for outbound calls. The default value for FreePBX is from-internal.

    autoPauseOnCommutationStart

    Ensures Asterisk queues work as intended. If enabled, Creatio puts the agent on pause in all queues after they answer a call. Prevents receiving additional calls while handling the first call or putting the first call on hold.

    queueExtensionFormat

    The format that determines the call channel for incoming calls from the queue. The default value for LocalChannel in FreePBX is Local/{0}@from-queue.

    sendRingStartedOnRingingState

    Ensures the retrieval of calls from the queue is handled correctly. If you select the checkbox, Creatio displays the calls to the user after receiving a 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. Logs agent status data to the connector log file. By default, "Off."

    protocol

    The protocol type: SIP or PJSIP. Contact your PBX administrator to determine the correct protocol type.

    filePath

    Use the parameter for system diagnostics. It lets you repeat a set of events from a pre-configured scenario file. The default value must be empty.

  8. Restart the CMS and test the phone integration. The connection to Asterisk is established on CMS startup, but packet handling begins only 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 configuration 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​

  1. Open the System Designer by clicking btn_system_designer00001.png in the top right corner of the application.

  2. Click System settings in the System setup block.

  3. ** Open the "Default messages exchange library"** ("SysMsgLib" code) system setting and set its default value to "Asterisk 13/16/18 (AMI) telephony integration library."

  4. 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 C:\Program Files (x86)\Terrasoft Messaging Service\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.
    note

    If your website is served over HTTPS and secure (WSS) connection is used for WebSockets, install a security certificate on the message exchange server and specify the certificate in the configuration files of the message service.

Set up the library on .NET Core or .NET 6​

Important

Messaging Host on .NET Core is supported in Creatio versions 7.16.3 through 8.0.8. Support for .NET Core 3.1 will be retired in Creatio version 8.0.9. We recommend migrating to .NET 6 when updating Creatio to version 8.0.8. Messaging Host on .NET 6 is supported in version 8.0.8 and later.

  1. Open the System Designer, for example, by clicking btn_system_designer00003.png in the top right corner of the application.

  2. Click System settings in the System setup block.

  3. Open the "Default messages exchange library" ("SysMsgLib" code) system setting and set its default value to "Asterisk 13/16/18 (AMI) telephony integration library."

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

      note

      If your website is served over HTTPS and secure connection is used for WebSockets, install a security certificate on the message exchange server and specify the certificate in the docker-compose configuration. For more information about the setup process, contact Creatio support.

4. Set up the Asterisk parameters​

Apply the Asterisk parameters 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. This opens a page.

  3. Fill out the following fields:

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

    2. Specify the Asterisk user line number in the Number field. The line number typically matches the phone number. For example, to track the SIP/305 user line, specify 305, and to track the SIP/office line, specify office.

      Important

      Each user should have an individual line. We recommend against assigning the same line to multiple users as this may cause errors.

    3. 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 C:\Program Files (x86)\Terrasoft Messaging Service\Terrasoft.Messaging.Service.exe.config file.

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

  4. Save the changes.

  5. Refresh the browser page to apply the changes.

See also​

Manage calls

Communication panel

Set up integration with Avaya

Set up integration with Cisco Finesse

Set up integration with CallWay