V3 Desk.com Integration

Owned by XCALLY Knowledge (Unlicensed)
Jun 10, 2022
8 min read

How it works


XCALLY Motion provides the integration with Desk.com, the Cloud Help Desk solution for customer care.

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


Please follow the steps below to setup the integration:

  1. Download and use the XCALLY Motion Phonebar Windows App and the XCALLY Motion Dialpad Chrome Extension 
  2. Create a new Integration in Desk.com 
  3. Create a new Desk Account in XCALLY Motion 
  4. Create a Desk Configuration for the account created in XCALLY Motion
  5. Create a Trigger, set the conditions you want to trigger and add integrations actions, by selecting the Desk integration, Desk Account and the Configuration you want to use.
  6. Login Agent in Desk.com and in Motion and start!
On this page:

Any interaction occurred through this integration can be searched by the Agent from the list by:

  • contact's phone number
  • user's email

After the configuration steps listed above, every time there is an outgoing/incoming call the trigger conditions are checked and a Desk.com Case is created and assigned to the agent managing the call (if the conditions are met).

When an agent manages a call, his account email address will be searched in Desk.com: if the system finds it the Desk.com Case will be assigned, otherwise the Case will be assigned to the Desk.com Administrator Account specified in Motion-Desk.com integration.

If all the configuration is properly set, the Desk.com Case will be opened as shown below:


The Case Subject, Description,Fields and Tags can be managed and customized in the Desk Configuration section.

Requirements - What to know before starting 


In order to have the integration working correctly, please be sure to:

  • use the Desk.com Next Gen Agent Console

  • install and use the XCALLY Motion Dialpad Chrome Extension, to allow Phone functionality in Desk.com. Using it, you can:

    • Click-to-Dial from Desk.com
    • Answer/Hangup calls directly from embedded phone in Desk.com

    You can download the XCALLY Motion Dialpad Chrome Extension here: https://chrome.google.com/webstore/search/motion%20dialpad?hl=en-GB

  • install and use the XCALLY Motion Phonebar

    You can download the Phonebar here: Phonebar Installation

    The integration will not work if your Agents are not correctly logged in the XCALLY Motion Phonebar (for example if they are using external phones)!


In order to create and assign Desk Case to Agents properly, make sure:

  • Agent's Email in Desk.com profile is exactly the same as Agent's Email in Motion
  • As for the Integration Type: 

    • For New Tab the Agent must be logged in XCALLY Motion Phonebar, XCALLY OmniDesktop Interface and Desk.com Web Interface. In this case the Agent must ENABLE the browser pop-ups, when he/she receives the first call.

      For New Tab Integration

      This type of integration works only through https connection to XCALLY Motion Server.

    • For Integration Tab the Agent must be logged in XCALLY Motion Phonebar and Desk.com Web Interface only. The Agents can manage calls through the Motion Phonebar or through the embedded phone on the Desk.com console. The login on the Motion Agent Web interface is optional. Remember to enable Remote control for the agents.







Create a new Integration on Desk.com Admin 

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


Go under Admin → Settings → Site Settings and enable Phone Integrations.


Go under Admin -> Channels -> Phone -> Integrations and click on the Add Integration button.



Fill in the form:

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 on Motion Admin

The Desk Accounts Section is under the Integrations Menu:

Create a Desk Account

To create a new Desk Account go in the Integrations Section → Desk Accounts and click on 

Enter the following details and click on Add Desk Account:

  • Type: chose between Integration Tab or New Tab
    • Integration Tab (OpenCTI Integration): the Case will be displayed in a new tab inside Desk interface. Remember to properly configure Desk to make the integration work (See Configure Desk for Open CTI Integration).
    • New Tab: the Case will be displayed in a new browser tab. Remember: this works only if the agent is logged in Motion interface.
  • URI: your Desk URL e.g. https://xyz.desk.com/api/v2/
  • Username: the Desk Administrator Account username
  • Password: the Desk Administrator Account password


After the Account is created, you can view it in the list of accounts, edit the account parameters and remove the account. 

You can verify if the account credentials are correct by clicking on Test Desk Account.

Edit a Desk Account

Find the account from the accounts list and Click on Edit Desk Account:



You will see two tabs: Account and Configurations

In the Accounts tab you can modify the account parameters and in the Configurations tab you can create, update or delete Desk configurations. 


Create a Desk Configuration

A Desk configuration is used to design the content of the Desk Case (Subject, Description and Fields) that is created and displayed for the agent managing calls.

You can create multiple configurations for a single Desk Account and use them in different triggers. In this way, for example, you will be able to use different Case layout for outbound and inbound calls.


To create a new configuration, edit the Desk account, go under configurations tab and click on Add Configuration

Please fill in the form: 

Choose a Name, Channel and Type and click on Add Desk Configuration.  

The configuration will be created with default Subject and Description settings that you can simply use without any modification.

The default Subject and Description settings depends on the type of configuration.

For example, the default subject configuration for Queue Type is [XCALLY Ticket] Queue calleridnum while for Outbound Type it's [XCALLY Ticket] Outbound Call destcalleridnum.

Configuration changes are automatically applied, without any service restart.

Remember you can use Motion Standard Variables or Custom Variables in the configuration.

You can also edit the configuration and customize the Subject, Description and Fields of the Desk Case according to your needs.


Subjects

By default, you will find the following three fields already configured

  • the String [XCALLY Ticket]
  • the Queue Variable
  • the Caller number Variable

You can add more than one field in the Subject and all fields will be joined by the blank space.

Use button to add a new fields. New fields are added at the end of the field list.

You can insert 3 different type of fields:

  1. String: static string e.g. a label as [XCALLY Ticket]
  2. Variable: Motion System Variable, e.g. queue or calleridnum (see V3 Motion Variable List)
  3. Custom Variable: any dynamic variable created under Tools > V3 Variables

Descriptions



You can add more than one field in the Description. All fields will be joined by new line.

Use button to add a new fields. New fields will be added at the end of the field list.

You can insert two different type of fields:

  1. String: static string e.g. *** Call Info ***
  2. Key Value: name-value item in the form name: value

where the first field is a static string (e.g. Caller Number) and the second field could be filled with the following:

  • String: static string
  • Variable: System Variable like Caller Number (see V3 Motion Variable List)
  • Custom Variable: dynamic variable created under  Tools > Variables

The colon character in the Key Value type is automatically added by the system

Fields


You can add more than one field.

In the drop-down list you can find the complete list of fields available in your Desk.com account: Standard and Custom Ticket fields.

Choose the field from the list (Standard or Custom):

and define the Type:

  • String: static string (you must insert it)
  • Variable: a System Variable (choose it from the list: e.g. Queue, uniqueid, calleridnum, etc.)
  • Custom Variable: one of the dynamic variables (created under Tools > Variables)
  • Picklist: choose among the list of the integrated Application Fields. You can only select one of the predefined values available for that field (if any).



Tags


You can add one or more Tags.

In the dropdown list you can find the complete list of available Tags.




Create a Trigger 

It is mandatory to create a Trigger to make the Desk integration work.

Go to Tools -> Triggers Section and click on New Trigger.

Enter the trigger Name, select Voice Channel and click on Add Trigger. 

Edit the trigger to define the trigger's Conditions and Actions.

Do not forget to set the trigger's status ON.

Add Trigger Conditions

You can use properties like Queue, Call status or outbound to define the conditions you want to trigger the Desk integration.

E.g.: in the following example the conditions set mean that the integration will be active for Calls in Sales Queue and when the call is answered. 

For more information on trigger conditions, take a look at Voice Trigger Conditions.


Add Trigger Action

To execute the Desk integration when the conditions are met, click on Add Action and select Integrations and Desk.

You can then select one of the the Desk account you have created and the configuration you want to use.




Using Desk.com & Motion Phonebar

Login agents in Desk.com web interface and in Motion Phonebar (the Motion server must be the same as the host configured in the Desk.com Integration URL) and experience the integration.

Agents can see the phone icon  in the top right of the Desk.com interface; clicking on they will open the embedded Motion Dialpad.

Please check to have installed the XCALLY Motion Dialpad Chrome extension to use Phone functionality in Desk.com.

The Chrome Extension is available here in the Chrome Web Store.


Troubleshooting

UNDER CONSTRUCTION

The Agent is logged with the Motion Phonebar and logged on Desk.com, however the Desk.com Case is not opened

  • Check that the agent can reach your Motion GUI via https

    If you don't have installed a valid certificate, the agent must open the https://your-motion-ip/ address and accept the insecure connection

    Please note that we recommend you to install a valid SSL certiticate on Motion (Install a valid HTTPS certificate).

  • Check that you have properly configured the integration on the Motion GUI and the Trigger