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
listener |
function |
function that is invoked when the Desk library and DOM are ready. |
Response
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
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
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
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:
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
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:;
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
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:
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
listener |
function |
JavaScript function that is invoked when a user clicks on a telephone number and enableClickToDial has been invoked. |
Response
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" }
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
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
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
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
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
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
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
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
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
callback |
function |
JavaScript method called upon completion of the method. |
Example
Response
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