Click To Call With JavaScript CTI Connector

Some time ago we have introduced Click to Call with VoIPstudio API functionality that allows you to create simple “click2call” user interfaces. The solution evolved from other older blog entry which introduced “c2c” with PHP-SIP class. Today I want to show you the next stage of c2c implementation evolution: JavaScript CTI Connector which allows for Computer Telephony Integration (CTI) of customer’s website or application and VoIPstudio Cloud PBX.

This integration does not require PHP or any other server side components anymore. The whole implementation is written in JavaScript and can be simply integrated into any application that supports JavaScript in the web browser.

This generic JavaScript CTI Connector is based on the recent work we have done to integrate our Cloud PBX platform with Salesforce and Oracle Sales Cloud. Our main goal was to allow for similar functionality to be available to Developers working on any web based applications which may benefit from VoIP (Telephony) integration.

Our CTI Connector is somehow similar to WebRTC as it offers rich real time communication controlled by web browser. However there are some major differences:

• it works in all web browser (as of time of this writing WebRTC is not supported by Internet Explorer which may limit its use in business applications);
• it is not a peer-to-peer technology and benefits from all advanced telephony functionality available in VoIPstudio platform;
• it offers connectivity to/from PSTN (Traditional Telephone) network “out of the box”;

Requirements

Strophe

Our Cti.Connector requires XMPP library for JavaScript: Strophe.js – Strophe uses BOSH (Bidirectional-streams Over Synchronous HTTP) to emulate a persistent, stateful, two-way connection to an XMPP server. More information about Strophe and XMPP can be found in official documentation.

VoIP Studio account

To be able to test our Connector you will need to sign up for a Trial account – if you haven’t got one already. This account offers all available functionality free of charge for a month.

VoIPstudio also announced limited time offer for the Developers Community – to allow for easy testing of CTI Connector they will be offering additional $5 of free credit for outbound calls and free Inbound Number in any of over 5000 cities in 50 countries.

The Connector

We recommend reading our official Cti.Connector documentation for implementation details. In this article I want to focus on implementation and integration.

First you need to download Cti.Connector from our repository and its dependencies (Strophe.js).

To install Cti.Connector in you application just copy/paste the following lines of code:

<script src="”https://cdnjs.cloudflare.com/ajax/libs/strophe.js/1.1.3/strophe.min.js”" type="”text/javascript”"></script>
<script src="”js/cti-connector.js”" type="”text/javascript”"></script>

And that’s all you need for integration.

Creating CTI Connector

To be able to communicate with VoIP Studio API you need to create Cti.Connector instance with proper configuration, authenticate and connect to XMPP API.

To do that you must pass only one parameter: onMessage to Connector’s constructor. But before doing that onMessage callback function must be defined. For you and your integration it is the most important part because onMessage function is listening to Connector’s events and can respond to them accordingly.

Here you can find all necessary information about events that Connector is sending.

var onMessage = function(event) {

    if (event.name === Cti.EVENT.LOGGED_IN) {
        // ...
    }

    if (event.name === Cti.EVENT.READY) {
        // ...
    }

    if (event.name === Cti.EVENT.RINGING) {
        // ...
    }

    if (event.name === Cti.EVENT.CONNECTED) {
        // ...
    }

    if (event.name === Cti.EVENT.ON_HOLD) {
        // ...
    }

    if (event.name === Cti.EVENT.HUNGUP) {
        // ...
    }
    
}

var connector = new Cti.Connector({
    onMessage: onMessage
});

Notice: Remember to add your custom implementation to respond to events that you are interested in.

Authentication

Now when Connector has been set, we can authenticate and connect to VoIP Studio API using your VoIP Studio credentials (username and password). It is as simple as calling login method on Connector instance with parameters:

var username = “test@example.com”,
    password = “secretpassword”;

connector.login(username, password);

After successfully authentication Connector should send events:
* Cti.EVENT.LOGGED_IN which means that user has been logged in;
* Cti.EVENT.READY which means that connection has been established.

We can also verify if user has been logged in and if connection has been established calling isConnected method:

connector.isConnected();

This method could be useful for example if you want to check if Connector is connected after refreshing the page.

To logout and close connection call logout method:

connector.logout();

After logging out Connector will send Cti.EVENT.LOGGED_OUT event.

Calls

Making a call

After receiving Cti.EVENT.READY event we are ready for making calls. To make a new phone call we need to call call method with destination number parameter in E164 format.

var destination = "+123456789";

connector.call(destination);

After that the following events will be send by Connector:

• Cti.EVENT.INITIAL – call initialization
• Cti.EVENT.ACCEPTED – to notify that caller picks up the phone;
• Cti.EVENT.RINGING – to notify that call is being established and callee’s phone is ringing;
• Cti.EVENT.CONNECTED – to notify that callee answered the call and the call is now established.

Notice: Each event has unique call ID that should be used to identify future call changes.

Transferring call

Established call can be transferred or terminated. To transfer call to other destination we need to call transfer method on Connector instance with callId parameter (to identify which call should be transferred) and destination number parameter in E164 format:

var callId = "1432549154470",
    destination = "+987654321";

connector.transfer(callId, destination);

After transferring call, Connector will send Cti.EVENT.HANGUP event with confirmation about successful operation.

Terminating call

To terminate given call we need to call terminate method with callId parameter:

var callId = "1432549154470",

connector.terminate(callId);

After terminating call, Connector will send Cti.EVENT.HANGUP event with confirmation about successful operation.

Error handling

In some cases Connector may send Cti.EVENT.ERROR event, for example when we pass invalid username and password during authentication or when we pass invalid destination number to call method.

Such events should be handled in onMessage function callback:

var onMessage = function(event) {

    if (event.name === Cti.EVENT.ERROR) {
        // each error event has proper message attribute
        alert(event.message);
    }
}

All implementation details can be found in our documentation (https://voipstudio.com/en/manual/Admin_Integrations-CTI-Connector).

Cti.Platform Quick Start

We encourage you to familiarize yourself with our example implementation:

1. Sing up for an account at https://voipstudio.com/en/register
2. Download and run softphone https://voipstudio.com/en/download (or use any other SIP client)
3. Pull cti-connector from Github to your PC
4. Open examples/cti-connector.html in your web browser
5. Login with your VoIPstudio email and password
6. Enter number you want to call

Getting help

If you hit any problems, find a bug or got an idea about expanding CTI Connector functionality, please open an Issue on Github and one of our developers will respond soon.

Good luck with yours integrations!