Skip to main content
Version: 8.3

Asterisk integration basics

Level: advanced

Use Asterisk Manager Interface (AMI) to interact with the Asterisk server. The API enables client programs to connect to the Asterisk server over TCP/IP, process call events, and send commands to control calls. Learn more: Asterisk Manager Interface (official vendor documentation). AMI uses a simple text protocol. Each line of a message has the "parameter: value" format and ends with a carriage return and line feed (CRLF).

Creatio provides the Asterisk V2 and Asterisk V1 (legacy) connectors for Asterisk integration. The Asterisk V2 connector supports Asterisk 13, 16, and 18. The connector uses AMI events introduced in Asterisk 12, for example, DialBegin, DialEnd, Hold, and Unhold. The Asterisk V1 (legacy) connector supports Asterisk up to version 13. Creatio uses the Asterisk V2 connector as the main connector. The Asterisk V1 connector applies only if an administrator selects the legacy library manually.

Asterisk connector classes​

The integration part of the Messaging Service is implemented in the main Creatio solution kernel. The Asterisk V2 connector is implemented in the Terrasoft.Messaging.Asterisk.V2 library, and the Asterisk V1 connector is implemented in the Terrasoft.Messaging.Asterisk library. Both connectors use the Terrasoft.Messaging.Asterisk.Common library.

The table describes the main classes of the connectors.

Class

Connector version

Description

AsteriskConnector

V2

The main class of the connector. Creates and manages operator connections and controls the CTI state machine.

AsteriskConnection

V2

Interacts with Asterisk. Subscribes to AMI events, passes them to the state machine, and sends AMI actions, for example, Originate and Hangup.

CtiConnection

V2

Represents the operator connection on the Creatio side. Receives commands from the "Calls" sidebar of the communication panel and passes them to the state machine.

CtiStateMachine

V2

Changes the state of operator extensions. Does not store the state.

OperatorExtension

V2

Represents an operator extension. Stores the call state.

OperatorExtensionListener

V2

Connects operator extension events to Creatio and Asterisk. Sends call events to Creatio and runs commands as AMI actions.

AsteriskAdapter

V1

Transforms Asterisk events to the top-level call model events used in Creatio integration. In the Asterisk V2 connector, the AsteriskConnection, CtiStateMachine, and OperatorExtensionListener classes share this role.

AsteriskManager

V1

Creates and deletes user connections to the Asterisk server. The main class of the connector.

AsteriskConnection

V1

Represents the user connection for integration with Asterisk.

AsteriskClient

V2, V1

Maintains the AMI connection to the Asterisk server and reconnects if the connection is lost. Sends AMI actions, and receives, parses, and filters AMI events.

Configure Creatio Messaging Service for Asterisk​

  1. Install Creatio Messaging Service (CMS) on a dedicated computer that serves as the integration server.

  2. Open the "Terrasoft.Messaging.Service.exe.config" file on the integration server.

  3. Set the parameters of the <asterisk> element.

    "Terrasoft.Messaging.Service.exe.config" file
    <asterisk
      url="{Name or address of Asterisk server}"
      port="{Asterisk server port}"
      userName="{Asterisk login}"
      secret="{Asterisk password}"
      originateContext="{Originate context}"
      queueExtensionFormat="Local/{0}@from-queue/n"
      protocol="PJSIP/"
      asyncOriginate="true"
      packetInfoConfig="{Additional package parameters to process}" />

    The table describes the parameters of the <asterisk> element.

    Parameter

    Description

    Default value

    url

    Name or IP address of the Asterisk server.

    —

    port

    Port of the Asterisk server for AMI connections.

    5038

    userName

    Login of the AMI user.

    —

    secret

    Password of the AMI user.

    —

    originateContext

    Dialplan context that CMS uses for outgoing calls (Originate AMI action) and for transfers started in Creatio (BlindTransfer and Atxfer AMI actions).

    —

    queueExtensionFormat

    Format of the queue member interface. {0} is replaced with the operator extension.

    Local/{0}@from-queue/n

    protocol

    Prefix of the operator channel name. Set "SIP/" if Asterisk uses the chan_sip channel driver.

    PJSIP/

    asyncOriginate

    Sends the Originate AMI action asynchronously. If the value is "true," Asterisk responds immediately and reports the result later in the OriginateResponse AMI event.

    true

    packetInfoConfig

    Additional AMI event parameters that CMS passes to the client in the additional data (privateData) of the event. The value is a JSON object. Each key is a regular expression for the AMI event name, and each value is an array of regular expressions for the parameter names. For example, {"DialBegin|Newstate": ["Uniqueid", "Linkedid"]}. The patterns must not match the Channel, CallerIDNum, and ConnectedLineNum parameters. Otherwise, the connector does not process the event.

    —

    The Asterisk V1 (legacy) connector also uses the following parameters:

    • parkingLotContext. Dialplan context of the parking lot. The connector uses it to retrieve the parked call when the operator takes the call off hold.
    • sendRingStartedOnRingingState. Reports an incoming call when the channel switches to the ringing state. If the value is "false," the connector reports the incoming call from the DialBegin event. Out of the box, "true."
    • traceQueuesState. Writes the state of Asterisk queues to the CMS log on call events. Use for troubleshooting. Out of the box, "false."
    • amiVersion. If the value starts with "1.", the connector reads the event parameters of AMI 1.x used in Asterisk 11 and earlier. Out of the box, empty.
    • autoPauseOnCommutationStart. Pauses the agent when any call connects, both incoming and outgoing. Out of the box, "true."

  4. Set up the integration ports.

    1. Allow incoming WebSocket connections to CMS on TCP port 2013.
    2. Allow connections from CMS to the Asterisk server on the port specified in the port parameter. Out of the box, 5038.

  5. Restart CMS to apply the changes.

As a result, CMS connects to the Asterisk server when the first user with the Asterisk library connects to CMS, and Creatio users can manage calls in the "Calls" sidebar of the communication panel. To check the connection, run the manager show connected command in the Asterisk CLI. The command output must include the AMI user. If CMS runs on .NET Framework, you can also check the "CMS_Logs\<date>\asterisk\asteriskV2" folder in the temporary folder of the CMS service account. The log must include the "Connected to Asterisk. Subscribe to Asterisk events." line.

Process an outgoing call​

The examples describe an outgoing call. The operator calls a subscriber, puts the call on hold, takes it off hold, and ends the call. The Asterisk V2 and Asterisk V1 connectors process the call differently.

Process an outgoing call using the Asterisk V2 connector​

In the example, the operator puts the call on hold and takes it off hold using the phone.

The figure below shows the order of events during the call.

In the Asterisk V2 connector, the AsteriskConnection class maps AMI events to commands, the CtiStateMachine class changes the operator state, and the OperatorExtensionListener class sends events to the client. After each event, CMS also sends the LineStateChanged event with the call actions available in the "Calls" sidebar of the communication panel. The connector does not process the Newchannel AMI event.

The table shows which events CMS sends to the client for Asterisk events during the call.

Asterisk event

Event sent to client

CtiModel class

{
    Event: DialBegin
    Uniqueid: <unique_id>
    ChannelStateDesc: Ring
}

RingStarted

Generates the callStarted event and shows the outgoing call in the "Calls" sidebar of the communication panel.

{
    Event: DialEnd
    Uniqueid: <unique_id>
    DialStatus: ANSWER
}

CommutationStarted

Generates the commutationStarted event and shows the conversation.

{
    Event: Hold
    Uniqueid: <unique_id>
}

PutHoldAction

Generates the hold event and shows the call on hold.

{
    Event: Unhold
    Uniqueid: <unique_id>
}

CallInfoChanged

Generates the callInfoChanged event and shows the active call.

{
    Event: Hangup
    Uniqueid: <unique_id>
}

RingFinished

Generates the callFinished event and shows the call end.

Process an outgoing call using the Asterisk V1 connector​

In the example, the operator puts the call on hold and takes it off hold in the "Calls" sidebar of the communication panel. The Asterisk V1 connector puts the call on hold using the Park AMI action.

The figure below shows the order of events during the call.

The table shows how CMS processes Asterisk events during the call and which events it sends to the client. The connector processes both the DialBegin event and the Dial event with SubEvent: Begin. If the amiVersion parameter starts with "1.", the connector reads the event parameters of AMI 1.x, for example, Bridgestate: Link instead of DialStatus: ANSWER.

Asterisk event

CMS

Event sent to client

CtiModel class

{
    Event: Newchannel
    Channel: <channel_name>
    Uniqueid: <unique_id>
}

Adds the channel to the collection.

new AsteriskChannel({
    Name: <channel_name>,
    UniqueId: <unique_id>
});

—

—

{
    Event: DialBegin
    Uniqueid: <unique_id>
}

Finds the channel by Uniqueid, populates the call data, and raises the event using the FireRingStarted() method of the AsteriskSipExtension class.

RingStarted

Generates the callStarted event and shows the outgoing call in the "Calls" sidebar of the communication panel.

{
    Event: DialEnd
    Uniqueid: <unique_id>
    DialStatus: ANSWER
}

Finds the channel by Uniqueid and raises the event using the FireCommutationStarted() method of the AsteriskSipExtension class.

CommutationStarted

Generates the commutationStarted event and shows the conversation.

{
    Event: ParkedCall
    Uniqueid: <unique_id>
}

Receives the event after CMS sends the Park AMI action. Finds the channel by Uniqueid and raises the event using the FirePutHoldAction() method of the AsteriskSipExtension class.

PutHoldAction

Generates the hold event and shows the call on hold.

{
    Event: UnParkedCall
    Uniqueid: <unique_id>
}

Receives the event after CMS sends the Originate AMI action to the parking space in the context specified in the parkingLotContext parameter. When the call is bridged with the operator channel, finds the channel by Uniqueid and raises the event using the FireEndHoldAction() method of the AsteriskSipExtension class.

EndHoldAction

Generates the unhold event and shows the active call.

{
    Event: Hangup
    Uniqueid: <unique_id>
}

Finds the channel by Uniqueid and raises the event using the FireRingFinished() method of the AsteriskSipExtension class.

RingFinished

Generates the callFinished event and shows the call end.

See also​

Telephony integration basics

Webitel integration basics

Set up integration with Asterisk (user documentation)

Resources​

Asterisk Manager Interface (official vendor documentation)

AMI events (official vendor documentation)