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

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

The integration automatically creates a Case for each call, according to the configured Queues and Triggers.

In the Embedded integration the Case is opened and shown to the Agent on the same TAB; the Agent can also manage calls using a phone embedded on the Desk.com interface.


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 please note that:

  • the integration WORKS ONLY if the Agents are logged on the XCALLY Phone bar (minimum version required: 3.7). The Agents can manage calls through the XCALLY Phone bar or through the embedded phone on the Desk.com console. The login on the Shuttle Agent Web interface is optional.

  • the integration WORKS ONLY if the Agents are using the Desk.com Next Gen Agent Console.

  • the integration WORKS ONLY if you force Chrome to always load the script.

    How to force Chrome to always load scripts

    1. Go under "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" and select chrome.exe. Click with the right mouse button on it. Select Send to Desktop in order to create a shortcut.

    2. Go to the Desktop and click with the right mouse button on the Chrome icon. Select Properties and, under the tab called Shortcut, edit the Target field adding after the application path --allow-running-insecure-content


    Target Field Sample: "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --allow-running-insecure-content

    Please note that your Agents must launch the browser ONLY from the Chrome Desktop icon.

    3. Verify that the point 2 has been correctly applied on your Chrome browser, launching the command chrome://version/strings.js on the Chrome nav bar. If everything is ok you will see the following screenshot (in particular the text highlighted). If you can't see the "--allow-running-insecure–content" string, please do again the step 2.


  • we suggest you to use the same Agent name on XCALLY and Desk.com.


Create a new Integration - Desk.com Admin

The Admin must create the integration on Desk.com following these steps:

  1. Go to Admin > Settings and enable the Phone Integrations.
  2. Go under Admin -> Channels -> Phone -> Integrations and click on the Add Integration button.


Fill in the form: choose a name for the integration (i.e. XCALLY), set the URL and the size of the embedded phone (recommended Height: 550 and Width: 300). 

Paste the following URL on the URL field. You need to insert your XCALLY Shuttle IP here: host=http://X.Y.Z.W i.e. host=http://10.9.8.7
URL: https://sf.xcally.com/integrations/opencti/v1/desk.html?host=http://X.Y.Z.W&port=8888&event=RealtimeCTI&path=/socket.io-client&type=desk&popup=true 

  • host: the ip or address of your shuttle server; insert here your XCALLY Shuttle IP
  • port: the port of shuttle server (default is 8888, do not change it)
  • event: the event sent from the shuttle server (default is RealtimeCTI, do not change it)
  • path: default is /socket.io-client, do not change it
  • popup: if true the embedded phone will appear when the phone rings (possible values: true or false)


You have also to select which Agents can use the integration clicking on their name.

At the end of this procedure, enabled Agents can see the phone icon  appear in the top right of the Desk.com interface.

Here you can find more information about adding a phone integration on Desk.com: https://support.desk.com/customer/portal/articles/1709557-add-a-phone-integration


Create a new Integration - Shuttle Admin

To create a new Integration click on the button New Integration. First of all select desk.com 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. https://xcally.desk.com/ -> CORRECT URI

https://xcally.desk.com -> WRONG URI, the integration won't work!

By default, the integration will be created as Embedded (Embedded flag) and the Agents will use the Next Generation Agent console.

If you would like to use the Classic integration you have to deselect the Embedded flag.

Finally you have to compile four fields (Consumer Key, Consumer Secret, Token, Token Secret) for the OAuth 1 authentication.

In the Desk.com 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

When one of the enabled Agents logs into the Desk.com Next Gen Agent Interface, he will find the icon of a Phone on the left of the top bar. Clicking on it, he can see and use the embedded phone.

He can manage calls from the XCALLY Phone bar or from the embedded phone, as he prefers, also using the click to call function. According to the Queues and Triggers configuration, the Agent will see the Case related to the call appear on the same tab of his Next Gen console.

The Case contains 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).

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.


Tags

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...)!


Troubleshooting

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 is correctly logged into the XCALLY Phone bar. 
  • The Agent is using the Desk.com Next Gen Agent console. 
  • You have correctly forced Chrome to always load the script.
    If you see on the browser the following icon, it means that you have not configured it correctly:


How to debug the application

If you want to debug the application you have to open the Console developer (on Chrome, ctrl+shift+j to open it or Menu -> More tools -> Developer tools -> Console tab).

If the application is running correctly, you will see, under the Logs, something like in the image below; instead, if you see some error messages, please contact our team!