Methods for Open CTI

Last Updated -

Note: This article explains the methods for using Open CTI to build a Phone integration. For information about how to add a SoftPhone integration to your Desk account, see Add a Phone Integration.

Supported Partners and Platforms

  • 8x8
  • AirCall
  • AMC Technology
  • Aspect (UIP, CS)
  • Avaya (AES, AACC, AIC, IP Office)
  • Cisco (UCCE, UCCX, UCM)
  • Five9
  • Genesys
  • NewVoiceMedia
  • Nortel (CCT)
  • OneReach
  • RingCentral
  • Talkdesk
  • ShoreTel
  • Vonage

Methods

 

​ready()

Usage

Utility function that allows a user to queue up functions to be invoked when the Desk library and DOM are ready.

Syntax

​Arguments

Name Type Description
listener function function that is invoked when the Desk library and DOM are ready.

Response

  • ​N/A

Differences to Salesforce API

  • ​No Salesforce equivalent. This is a needed change for best practices so we don't block when we load the Desk library.

Example

​back to top

 

setSoftphoneHeight()

Usage

Sets the softphone height in pixels.

Syntax

​Arguments

Name Type Description
height number Softphone height in pixels. The height should be a number that’s equal or greater than 0.
callback function JavaScript method called upon completion of the method.

Example

Response

Name Type Description
result boolean true if the height was set successfully, false if setting the height wasn’t successful.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.

 

back to top

setSoftphoneWidth()

Usage

Sets the softphone width in pixels for the Desk.com console.

Syntax

​Arguments​

Name Type Description
width number Softphone width in pixels. The width should be a number that’s equal or greater than 0.
callback function JavaScript method called upon completion of the method.

Example

Response

This method is asynchronous; it returns its response in an object in a callback method. The response object contains the following fields:
 
Name Type Description
result boolean true if the width was set successfully, false if setting the width wasn’t successful.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.

 

back to top

enableClickToDial()

Usage

Enables click-to-dial.

Syntax

​Arguments

Name Type Description
callback function JavaScript method called upon completion of the method.

Example

Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:;

Name Type Description
result boolean true if click-to-dial was enabled, false if click-to-dial wasn’t enabled.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.
 

disableClickToDial()

Usage

Disables click-to-dial.

Syntax

Arguments

Name Type Description
callback function JavaScript method called upon completion of the method.

Example

​Response

This method is asynchronous so it returns its response in an object in a callback method. The response object contains the following fields:
​
Name Type Description
result boolean true if click-to-dial was disabled, false if click-to-dial wasn’t disabled.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.

​  

onClickToDial()

Usage

Subscriber helper function when a telephone number is clicked.

Arguments

Name Type Description
listener function JavaScript function that is invoked when a user clicks on a telephone number and enableClickToDial has been invoked.

Response

Name Type Description
result object returns the number, objectId, and object (customer/company/case) type. If the function invocation fails, result should be null.
 

Example

{ number: "12345677890", objectId: "1", object: "case" }

Name Type Description
error string if an error occurred while clickToDial was invoked, an error message is sent.

Example​

"Resource Object does not exist."

Differences from Salesforce API

  • object types on the result object are restricted to values of customer, company, or case.​

Example​​

back to top

screenPop()

Usage

Routes to the view of an object type using an id. (case/customer/company).

Syntax

Arguments

Name Type Description
id string id used to route to the specific object type.
queryParams string specifies the query parameters used for a screenPop. We require that you pass in the object type (case/customer/company).
callback function optional callback function invoked when screenPop API invocation is completed.

Example

Response

Name Type Description
result boolean true if the screenPop was successful, false otherwise.
error string if the screenPop was successful, this property will not be on the response object. If the screenPop was not successful, this property will contain an error message string.

Differences to Salesforce API

  • instead of a url:String as the first argument, we require an id:String.
  • we require a queryParams:String as the second argument with the object key and a value of either customer, company, or case.

​​Example

​back to top

 

searchAndScreenPop()

Usage

​Searches for an object type using a searchString. When object is customer and an exact match is found, a phone case is automatically created for that customer. When object is case, a list of matching cases is listed. When object is company, a list of matching companies are shown.

Syntax

Arguments

Name Type Description
searchString string string used for search.
queryParams string specifies the query string parameters used for a searchAndScreenPop. We require that you pass in the object type (case/customer/company).
callback function optional callback function invoked when searchAndScreenPop API invocation is completed.
 

Example

Response

Name Type Description
result boolean true if the searchAndScreenPop was successful, false otherwise
error string if the searchAndScreenPop was successful, this property will not be on the response object. If the searchAndScreenPop was not successful, this property will contain an error message string.

Differences to Salesforce API

  • ​we require a queryParams:String as the second argument with the object key and a value of either customer, company, or case.

​Example

back to top

getPageInfo()​

Usage

Gets the current page's information. Only case/customer/company pages are supported and any other page will return an error if getPageInfo is called while on that unsupported page type.

Syntax

​ ​

Arguments

Name Type Description
callback function Mandatory callback function invoked with the response object.

Response

  • result (Object) - object containing the following fields:
    • url - current page url.
    • objectId - current objects id.
    • object - current objects type.
    • objectName - objectName is dependent on the type of object in focus. If it is the customer or company object then the objectName is the name. If it is the case object then the objectName is the case subject.
  • error (String) - If getPageInfo was successful this property will not be on the response object. If anything went wrong while invoking getPageInfo this property will contain an error message string.

Differences from the Salesforce API

  • object types are different from Salesforce and are Desk-specific.
  • not all fields supported by Salesforce are supported by Desk.

​Example


​onFocus()

Usage

Accepts a callback function that is invoked when a case/customer/company object is in focus. Information about the object is passed to the callback function.

Syntax

Arguments

Name Type Description
callback function Mandatory callback function invoked when a case/customer/company object is in focus.

Response

  • result (Object) - object containing the following fields:
    • url - current page url.
    • objectId - current objects id
    • object - current objects type.
    • objectName - objectName is dependent on the type of object in focus. If it is the customer or company object then the objectName is the case subject.
  • error (String) - If onFocus was successful this property will not be on the response object. If anything went wrong while invoking onFocus​ this property will contain an error message string.

Differences fro the Salesforce API

  • object types are different from Salesforce and are Desk-specific.
  • not all fields supported by Salesforce are supported by Desk.

Example

 

 

setVisible()​

Usage

Shows or hides the Softphone in the Desk console.

Syntax

Arguments

Name Type Description
value boolean Set value to true to show the Softphone or set value to false to hide the Softphone.
callback function Optional callback function invoked when setVisible api invocation is completed.
 

Example

Response

​
Name Type Description
result boolean true if showing or hiding the Softphone succeeded, false if showing or hiding the Softphone didn’t succeed.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.
 

isVisible()

Usage

Returns true if the Softphone is visible or false if the Softphone is hidden.

Syntax

Arguments

​
Name Type Description
callback function JavaScript method called upon completion of the method.
 

Example

Response

Name Type Description
result boolean true if the Softphone is visible, false if the Softphone isn’t visible.
error string If the API call was successful, this variable is undefined. If the API call failed, this variable returns an error message.
 
 

getUserInfo

Arguments​

  • callback - function - Callback function invoked with the response object

Response

  • result (Object) - object containing the following fields:
    • user ID - agent ID
    • email - agent email address
    • userName - agent user name (usually the email address)
    • fullName - agent full name
    • profilePhotoUrl - agent avatar
    • profileThumbnailUrl - agent avatar
    • userType - agent access level
    • language - agent language preference
    • locale - agent language preference
    • siteUrl - the company's site URL
  • error (String) - If getUserInfo was successful this property will not be on the response object. If anything went wrong while invoking getUserInfo this property will contain an error message string.

Differences from the Salesforce API

  • not all fields supported by Salesforce are supported by Desk.

Example

​ajax()

Syntax

Arguments

  • url - string - url to which the request is sent
  • config - object - a set of key/value pairs to configure the ajax request. All settings are optional. Currently supported options are: ​
    • method - string - http method to use for the request
    • data - string/object/array - data to be sent to the server (for PATCH, PUT, or POST requests)
    • callback - function - Callback function invoked with the response object

Response

  • result (Object) - object containing the following fields:
    •  data - string/object - response body
    • status - number - http status code response
    • statusText - string - corresponding text for http status code
  • error - object - object containing the following fields:
    • message - string - error message
    •  status - number - http status code response
    •  statusText - string - corresponding text for http status code

Example


 

​back to top


Related Articles