Integrations - CTI Connector

VoIPstudio CTI Connector allows for Computer Telephony Integration (CTI) of customer website or application.

It does not matter if it's simple Content Management System (CMS), e-commerce application or advanced Customer Relationship Management (CRM). Connector can be used as a standalone component in almost any kind of environemnt that supports JavaScript. Connector supports both outbound (click to call also known as c2c) and inbound calls - this has been described below:

1) Outbound click to call connections to PSTN (Traditional Telephony Network) from within Customer application involves clicking telephone number link or button in the user interface which triggers VoIPstudio network to place a call to SIP endpoint (IP Phone or Softphone) registered on the user account. As soon as this call is answered it is being transferred to the number clicked.

2) Incoming calls received from PSTN (Traditional Telephony Network) generate real time notifications about call state (Ringing, Connected, On Hold, Disconnected) which should be handled in customer's application user interface.

In both scenarios described above once the call is established user can control call state using VoIPstudio CTI Connector API. Ongoing connections can be transferred to a different PBX user or external number or disconnected.

Requirements

Cti.Connector requires sip.js - SIP library for JavaScript to be included before connector code. SIP uses WebSockets to maintain a persistent two-way connection to an SIP server which is used as a bridge between JavaScript and SIP telephony network.

Connector's Events

To integrate Connector into you application you need to respond to Cti.Connector events. To be able to receive events and respond to them, we need to pass callable function as a onMessage config parameter.

Note: Event flow has been also described in VoIPstudio` example integration.

Types of events

Connector sends (fires) the following events:

• LOOGED_IN - after successful authentication to VoIPstudio;
• LOGGED_OUT - after successful logging out from VoIPstudio;
• INITIAL - when caller SIP endpoint is ringing - occurs only for OUTBOUND calls;
• ACCEPTED - when caller SIP endpoint accept the call (picks up the phone) - occurs only for OUTBOUND calls;
• READY - after connection has been established with SIP server;
• RINGING - when server is trying to established OUTBOUND or INBOUND call;
• CONNECTED - after OUTBOUND or INBOUND call has been established with callee;
• ON_HOLD - when caller or callee suspends the call;
• HANGUP - when caller or callee ends the call;
• CANCEL - when call is not yet connected and error occurs;
• INFO - when action cannot be executed for some reason but the error did not occur;
• ERROR - when any kind of error occurs, for example: incorrect username and password during the authentication, incorrect phone number format, not permitted call action etc.

Event flow

Here are some typical scenarios.

OUTBOUND call:

• INITIAL - caller SIP endpoint
• ACCEPTED - caller SIP endpoint
• RINGING - dialled number is ringing
• CONNECTED - connection with dialled number established
• HANGUP - call terminated

INBOUND call:

• RINGING - user phone is ringing as a result of an inbound call
• CONNECTED - inbound call established
• HANGUP - call terminated

Event structure

There are two types of events:

• ''activity'' events: LOGGED_IN, LOGGED_OUT, READY, INFO, ERROR;
• ''call'' events: INITIAL, ACCEPTED, RINGING, CONNECTED, ON_HOLD, HANGUP, CANCEL;

Each ''activity'' event sent by Connector contains two attributes:

• name - event name;
• message - message with event description / reason;

Example events:

The above image shows five steps:

1. Platform ready: Connector and other JavaScript files have been successfully loaded, user is not authenticated yet; The first step is to connect to VoIPstudio application via Cti.Connector. This requires providing valid e-mail address and password from you VoIPstudio account; Entering invalid data will trigger ERROR event with proper message;
2. Connector is now READY: after successfully authentication we have received LOGGED_IN event, and later after the connection has been established connector sent READY event - we are now ready to make outbound calls and to receive INBOUND calls;
3. Making outbound call: after entering phone number and clicking Outbound call button, Connector sent INITIAL event. It means that the caller's softphone is now ringing and waits for call acceptance. ''This occurs only for OUTBOUND calls'';
4. After accepting the call by caller (picking up the phone), Connector sends ACCEPTED event. Now the ringing process can start. If callee could not accept the call, was busy or unreachable, Connector will send CANCEL event with proper cause property. ''This occurs only for OUTBOUND calls'';
5. Connector sent RINGING event to notify our app that is trying to establish new connection - callee phone is now ringing; If connection could not be established, the ERROR event with proper message will be returned;
6. Receiving INBOUND call: when connection is being established, connector will send RINGING event with caller information. This information can be used for example to identify caller, open call history or to display caller details;
7. Connector in now CONNECTED: when callee answer our OUTBOUND call or after answering INBOUND call, connector will send CONNECTED event which means that call has been established. Having active call we can terminate it or transfer to other phone number. After terminating or transferring call we will return to step 1.

We encourage you to familiarize yourself with this implementation.

We called it Cti.Platform as it contains all necessary code to integrate Cti.Connector with example app build with Bootstrap. With this sample code you can authenticate to VoIPstudio app and make, transfer and terminate calls. This basic functionality can be easily extended depending on customer needs.