Skip to main content
Version: 8.1

Asterisk integration basics

Level: advanced

Use AMI (Asterisk Manager Interface) to interact with the Asterisk server. The API enables client programs to connect to Asterisk server by using TCP/IP protocol. The Application Programming Interface enables you to process events in the digital multiplex system (DMS), and send commands to control calls.

note

Currently the integration of Creatio with Asterisk is supported up to version 13.

A client uses a simple text protocol for communication between the Asterisk and the connected Manager API: "parameter: value". The end of a string is determined by the sequence of Carriage Return and Line Feed (CRLF).

note

In the future, for a set of strings like "parameter: value", followed by a blank line containing only a CRLF, for simplicity the term "package" will be used.

Set up the configuration file of the Messaging Service to integrate Asterisk to Creatio​

For integration to work with Creatio, you need to install Terrasoft Messaging Service (TMS) on a dedicated computer that will be used as the integration server. You must set the following parameters for Asterisk in the Terrasoft.Messaging.Service.exe.config configuration file:

Parameters for Asterisk
<asterisk filePath="" url="Name_or_address_of_Asterisk_server" port="Asterisk_server_port"
    userName="Asterisk login" secret="Asterisk password" originateContext="Originate context" parkingLotContext="Parking lot context"
    autoPauseOnCommutationStart="true" queueExtensionFormat="Local/{0}@from-queue/n" asyncOriginate="true" sendRingStartedOnRingingState="true"
    traceQueuesState="false" packetInfoConfig="Additional package parameters to be processed in configuration" />

Ports for Asterisk integration with Creatio​

  • TMS accepts WebSocket connection to the 2013 port via TCP.
  • TMS connects to the Asterisk server by default via the 5038 port.

The Terrasoft Messaging Service for Asterisk integration with Creatio​

The integration part of the Messaging Service is implemented in the main Creatio solution kernel in the Terrasoft.Messaging.Asterisk library.

Library main classes:

  • AsteriskAdapter – an Asterisk class that transforms events to the top-level call model events used in Creatio integration.
  • AsteriskManager – a class that creates and deletes user connections to the Asterisk server.
  • AsteriskConnection – a class that represents the user connection for integration with Asterisk.
  • AsteriskClient – a class used to send commands to the Asterisk server.

Example of CtiModel, Terrasoft Messaging Service and Asterisk Manager API interaction​

Operator outgoing call to a subscriber: putting a call on hold, putting off hold by a subscriber and finishing the call by the operator.

The order of events during a call for the current example:

The table shows an example of event processing including how the event data is interpreted by TMS and which values from the listed events are used when processing an incoming call.

Asterisk log

TMS

Action

Client

{
    Event: newchannel
    Channel: <channel_name>
    UniqueID: <unique_id>
}

A channel is created and added to a collection

new AsteriskChannel({
    Name: <channel_name>,
    UniqueId: <unique_id>
});
{
    Event: Hold
    UniqueID: <unique_id>
    Status: "Off"
}

Search for the channel by <unique_id> and generate an event by using the fireEvent method.

PutHoldAction

Processing the PutHoldAction and displaying the call on hold.

{
    Event: Hangup
    UniqueID: <unique_id>
}

Search for the channel by <unique_id> and generate an event by using the fireEvent method.

EndHoldAction

Processing the EndHoldAction and displaying the call on hold.

{
    Event: Dial
    SubEvent: Begin
    UniqueID: <unique_id>
}

Search for the channel by <unique_id> and generate an event by using the fireEvent method.

RingFinished

Processing event and displaying the call end.

{
    Event: Dial
    SubEvent: Begin
    UniqueID: <unique_id>
}

Search for the channel by <unique_id>, fill in the data and generate an event by using the fireEvent method.

RingStarted

Processing the RingStarted event and displaying it on the outgoing call panel.

{
    Event: Bridge
    UniqueID: <unique_id>
}

Search for the channel by <unique_id> and generate an event by using the fireEvent method.

CommutationStarted

Processing the CommunicationStarted event and displaying the communication.

Clicking the "Answer" button initiates a new event in Asterisk.

Asterisk events​

A detail list of events and information about their parameters is described in the [Asterisk documentation](https://wiki.asterisk.org/wiki/display/AST/Asterisk 11 AMI Events).