API CTI: Custom integration – previous releases

You can integrate xCALLY Shuttle with any kind of external Web Applications you like (external custom CRM, Ticketing solution, ERP etc…).

The template.js file contains the basic elements to create your Custom CTI Integration through the realtime xCally Shuttle connection, thus providing the possibility to manage and autofill your external applications with the data about the call, like the caller number or the agent who answered the call and more. You can automatically open a CTI form or pop-up, and view the call/ticket/crm data on to the xCALLY Shuttle supervisor Realtime Dashboards.

 xcally API - CTI Custom


You can download the template_integration.zip here: template_integration

In this archive you can find 2 files:

1. The template execution file
You have to copy the template execution file in the /etc/init.d/ directory to add the service.

2. The template.js file
We recommend you to copy the file template.js in the directory /var/www/html/.

If you choose a different directory you need to check if the node.js dependencies are installed: in the example provided by us is necessary just to run npm install socket.io.

In addition, you must edit the template file (copied in /etc/init.d/) indicating the exact path.


The parameters which can be configured for the integration are the following:

  • socket_server: the xCally Shuttle address server
  • event_type: the kind of event which triggers the integration. Values: ringinguphangup – abandon
  • queue_name: the name of the queue involved in the integration
  • var_name_array: an array of desired variables, also present in Asterisk, valid for the current call. For example, it’s possible to define a Set application on the Dialplan.
  • mode_open: how the CTI form will be opened. Values: new_tabnew_window – new_frame

There are also some Asterisk Events which are involved in the service:

  • AgentCalled: when the agent’s phone is ringing
  • AgentConnect: when the agent answered the call
  • AgentComplete: when the channel has been closed (hungup)
  • QueueCallerAbandon: when the caller abandons the call

The main element of the service is the handleIntegration function, through which it’s possible to:

  • get variables values (GetVariable event) for each variable name present in the array var_name_array
  • open the CTI form (AgentCTI event)
  • send data to the administrators (Realtime)

For the AgentCTI and Realtime events it’s necessary to follow the rigid structure of parameters.

AgentCTI Event Parameter

var jsonAgent = {
        url : url,
        peer : channel.agentcalled,
        mode : mode_open


– url is the address of the CTI form which you want to open. It’s possible to send parameters on the address by GET.
An example is present in the template.js file:


peer is the agent interface

mode is how the CTI form will be opened.

IntegrationCTI Event Parameter

var jsonRealtime = {
type : 'custom',
channel : channel,
reference : channel.customId


type is the kind of integration. In this case the value must be set as custom

reference is relative to the form CTI creation id

channel is an array containing the data about the call, the caller and the agent. Some of these informations are fundamental and indispensable for the data visualization on the xCally Shuttle Interface:

  • time: call time
  • queue: the queue of the call
  • calleridnum: the caller number
  • calleridname: the caller name
  • connectedlinenum: the agent number
  • connectedlinename: the agent name


To start the service you have to follow this instructions:

– copy the template file (which is on the archive) in the directory /etc/init.d/

– execute the command chkconfig –-add template

– execute service template start