Telephony integration basics

Level: advanced

note

The functionality is relevant to Classic UI.

Creatio can be integrated with a number of automatic telephone exchanges (Private Branch Exchange, PBX), which enables users to manage calls directly in Creatio UI. Phone integration functions are available in the form of a CTI (Computer Telephony Integration) panel, as well as the Calls section. Standard CTI panel functions:

• Displaying incoming calls with contact/account identification by the subscriber's phone number.
• One-click calls initiated from Creatio UI.
• Call management (reply, place on hold, end or transfer call).
• Displaying call history for managing connections of calls to various system records and call follow-up.

All calls made or received are stored in the Calls section. In this section, you can view when a call was started, when it ended and how long the call was; as well as the list of system records connected to the call.

By default, Creatio cloud has a function for making calls between system users without using any additional software.

Depending on the integrated phone system and specifics of its API (Application Programming Interface), different architectural mechanisms are used. The API also affects available phone integration functions. For example, the call playback function is not available for all phone systems, the web phone is available when integrating with Webitel, etc. Regardless of the phone integration mechanism being used, the CTI panel interface remains the same for all Creatio users.

Phone integration methods in Creatio

There are two types of integration methods: first party and third party integrations.

In a first party integration each user has a separate integration connection. Phone system events are handled as part of that connection.

For a third party integration, a single connection to the prone system server is used for handling phone system events for all users. In a third party integration an intermediate Messaging Service link is used for distributing information streams for all users.

JavaScript adapter on the client side

When integrating with JavaScript adapter on the client side, the work with the prone system is done directly from a web browser. Interactions with the phone system and JavaScript-library, usually supplied by the prone system manufacturer, is done through the phone system API. The library broadcasts events and accepts execution commands using JavaScript. In the context of this integration, the Creatio page interacts with the application server for authentication using the HTTP(S) protocol.

This integration method can be used with a first party phone system API, such as Webitel, Finesse. Webitel connector use WebSocket as connection protocol, while the Finesse connector uses long-polling http queries.

The advantage of the first party integration method is that it does not require any additional nodes, such as Messaging Service. Using an integration library, the CTI panel connects directly to the phone system server API from a browser on the user's PC.

For incoming calls the phone server passes the new call start event and call parameters through WebSocket to the client integration library. When receiving a new call command, the library generates the RingStarted event that is passed to the application page.

For incoming calls, client part generates the call start command that is passed through WebSocket to the phone integration server.

Terrasoft Messaging Service on the server side

If integrating with Terrasoft Messaging Service (TMS) on the server side, all phone integration events pass through TMS, which interacts with the phone system through the manufacturer's library. The library interacts with the phone system through the API. TMS also interacts with the Creatio application server for executing query for saving call information in the database using HTTP(S). Interaction with a client application, such as passing events and receiving commands, is done via WebSocket. In case of integration with JavaScript adapter on the client side, Creatio page interacts with the application server for authentication, using HTTP(S).

This integration method applies to third party phone system API (TAPI, TSAPI). This integration type requires Messaging Service – a Windows proxy service that works with the phone system adapter library. The Messaging Service is a universal phone system library hoster, such as Asterisk, Avaya, Callway, Ctios, Infra, Tapi. When receiving client messages, the Messaging Service automatically connects used Creatio library and initiates connection to phone system. The Messaging Service is essentially a functional wrapper for those phone integration connectors that do not support client integration for interacting with phone functions in browsers (event generation and handling, data transfer). A user's PC conducts two types of communication:

• HTTP connection with Creatio application server for authentication with host on which the Messaging Service is installed;
• WebSocket connection for working directly with phone integration.

For incoming calls the phone system passes the new call start event and call parameters through the adapter library. When receiving a new call command, the Messaging Service generates the RingStarted event that is passed to the client.

For an outgoing calls, the client generates a call start command, which is passed via WebSocket to the Messaging Service, which generates an outgoing call message for the phone system.

Interaction between the phone connectors and Creatio

All connectors interact with configuration through the CtiModel class. It handles the events received from the connector.

View the list of supported class events is provided in the table below.

Event	Description
initialized	Triggered on completion of provider initialization.
disconnected	Triggered on provider disconnection.
callStarted	Triggered at the start of a new call.
callFinished	Triggered after call completion.
commutationStarted	Triggered after establishing call connection.
callBusy	Triggered on changing call status to "busy" (TAPI only).
hold	Triggered after placing call on hold.
unhold	Triggered after resuming a call.
error	is triggered on errors.
lineStateChanged	Triggered after changing available operations for a line or a call.
agentStateChanged	Triggered on changing the agent status.
activeCallSnapshot	Triggered on updating the list of active calls.
callSaved	Triggered after creating or updating a call in the database.
rawMessage	Generic provider event. Triggered on any provider event.
currentCallChanged	Triggered on changing the main call. For example, primary call ends during a consultation.
callCentreStateChanged	Triggered if an agent enters or exits Call center mode.
callInfoChanged	Triggered on modifying a call data by database Id.
dtmfEntered	Triggered if Dtmf signals were sent to the phone line.
webRtcStarted	Triggered on a webRtc session start.
webRtcVideoStarted	Triggered on a webRtc video stream session start.
webRtcDestroyed	Triggered on a webRtc session end.