Page tree
Skip to end of metadata
Go to start of metadata

xCALLY Shuttle provides a seamless CTI integration with, the Cloud Help Desk solution for multi-channel customer cares.

The Classic integration automatically creates a Case for each call; the Case will be opened and shown to the Agent on a new TAB.

The guide contains these sections:

Important configurations and hints

The integration between xCally Shuttle and Desk uses the new Shuttle Push Technology in order to speed the Case creation and agent pop-up.
In order to have it working properly you need to be sure that:

1. the Agent Name in the Desk profile corresponds exactly to the Agent Name in the xCally Shuttle Agent profile, like shown in the images below. 

xCALLY phone bars: if you use the xCALLY phone bars, you just need to create the Agents, being careful to fill in with the Name same as your Desk AGENT NAME. Do not touch the Caller-ID SIP created field (it will be automatically generated with the right value to make the integration working).

External IP phones: if you use external IP phones, or experimental WebRTC, you just need to create the Agents, being careful to fill in with the Name same as your Desk AGENT NAME.
Afterwards, just link the Agent to the SIP username related to your external IP phone.
The Caller-ID SIP field and the entire SIP related account, can be modified later on without any impact.

2. the Agent is correctly logged into the xCALLY Shuttle web interface and in the Desk web interface;

3. the Agent has ENABLED the browser pop-ups, when he received the first call, as shown in the image below:

If the Agent doesn't enable popups, the integration will NOT work!


Create a new Integration

To create a new Integration click on the button New Integration. First of all select as Type and then fill the form with the other information:

You can choose a Name which represents the Integration and then fill the Username and Password fields, which require the same username and password of an Administrator Desk Account. Then compile the URI field with your Desk URL.

IMPORTANT: the URI must end with /

e.g. -> CORRECT URI -> WRONG URI, the integration won't work!

Finally you have to compile four fields (Consumer KeyConsumer SecretTokenToken Secret) for the OAuth 1 authentication. You can find those information into the Desk Admin -> Settings -> API, as shown below.

In the Desk Admin -> Settings -> API you have to add an API application for xCALLY, as shown in the image below:

After submitting the form you will see the created xCally Application.
Now you need to collect the Customer Key, Customer Secret, Token and Token Secret to insert into the xCALLY Integration creation form.

You can immediately find the Customer Key and Secret:

To obtain the Token and the Token Secret you have to click on Your Access Token:


Create a Trigger

Now let’s focus on the Triggers Section: here you can set how the integration works by adding a new Trigger. To create it click on New Trigger and choose your integration strategy filling the form:

Through the Event field you can decide when the integration starts, so when the Desk Case page (dedicated to the actual call, which includes all the relevant fields of the caller) will be created:
- Ringing: when the phone is ringing, before the agent’s answer
- Up: when the agent picks up the call
- Hang up: when the agent hangs up the call
- Unmanaged call: when the caller has hang up before talking with an agent

You can also choose for which Queue the integration is valid. If you need to apply the Integration on more queues, you have to create one trigger for each queue.
Then you have to select the Desk Integration and finally you can associate some Tags to the Desk Cases created by the integration.

After the creation of the Trigger you can edit parameters or remove it.


The result

If you have configured correctly the Integration, you will have this Result on Desk: every time a call incomes there will be displayed the associated Case with the main information about the Caller, the Agent, the Call (like the Recording link, if the recording is enabled) and also the Custom Fields and Custom Variables, to show useful information to the Agents, and the Tags (if you have set them from the xCALLY Shuttle interface).

If you notice some problems, please see the Troubleshooting section.


Custom fields

Custom Case Fields are typically used to gather more information about the support issue or product or service in Desk.
Each Desk custom field is associated to one key.
Using Shuttle you can now create a MAPPING between the Desk custom field key and the available field values.
In order to do it just enter in the Shuttle administration web interface -> Section Integrations and add your custom field mapping in the Custom Fields sub-section clicking on New Custom Field.

Fill the form with the requested information:










Custom Field ID: insert here the Desk Custom Field key, in this case xcally_queue


In Desk, under Admin -> Settings -> Case -> Cases -> Custom Fields you can add and edit your custom fields.
For each of them you can set the key that you have to insert into the Shuttle ID field.

Prefix: String prefix

- Available Fields

  • From: Caller 
  • Date: Enter Time Call 
  • To: Called 
  • Unique ID: Asterisk Unique ID Call 
  • Id: Caller ID Zendesk 
  • Recording Link: Link Recorded Call 
  • Name: Caller Name 

  • SIP: Shuttle SIP 
  • Queue: Shuttle Queue 
  • Agent: Shuttle Agent 
  • Position: Queue’s Position 
  • Count: Queue’s Count 
  • Trunk: Shuttle Trunk 

- Suffix: String Suffix 

- Integration: Integration Name




Here the result in the Desk: your agents will get the Case pop-up with the custom fields auto-filled.


Custom Variables

In the Settings -> Integrations section there is a submenu where you can create Custom Variables to be used in the Cally Square section when designing the IVR structure.
In this way you can pass useful data to the integrated 3rd party applications, as Desk.
Click on the New Custom Variable button and fill the form with the Name and the Alias. In order to use the variable, you have to select Active, as shown in the image below.

The image below shows an example of how you can use the Custom Variable in the IVR structure:

Here the result in the Desk: you can find the customer Order number into the Additional Info of the Case.



In the Shuttle Settings -> Tags section you can manage Tags, that you can see in the Desk case under the Labels.
First of all, you can create a Tag clicking on the New Tag button.
Simply type the Tag Name, its Description and click on Save Changes.

After that, you will see your new Tag into the Tag tab, where you can edit or delete it.
In the Integration -> Trigger section, when you set a Trigger for the Desk Integration, you can specify one or more tags that will be added to the Desk Case created by the integration, as shown in the image below.


Desk Outbound CTI Integration

The xCALLY - Desk Integration can be also applied to an Outbound Route: a Case is created and shown through a pop-up every time an Agent starts an outbound call.
First of all, you need to have an Integration already created (Settings -> Integrations menu).
Then you have to go to the Dial Plan -> Outbound section, click on edit on the route of interest, go under the General Settings and choose the Integration from the list.

In case you enable the Desk integration for outbound call rules, please note one Case will be presented to the agent, for each OUTBOUND CALL TENTATIVE, independently from the outbound call result (busy, congestion, answer etc...)!



The Integration doesn’t work? Check carefully the following steps:

  • the username and password correspond to a valid Desk Admin Integration Account
  • the Desk URI is correct
  • the Consumer Key, Consumer Secret, Token, Token Secret are correct
  • The Agent is correctly associated to the Queue specified in the Trigger that you created (xCally Shuttle - Integration Settings)
  • The Agent Name in the Desk profile corresponds exactly to the Agent Name in the xCally Shuttle Agent profile. 
  • The Agent is correctly logged in the xCALLY Shuttle interface and the Desk interface. 
  • You have enabled browser pop-ups