Udesk Call Center Integration Guidelines

Udesk call center support allows invoking interfaces of third-party systems during phone calls, executing different logics based on different return values of the interface. Typical application scenarios include:

  • Caller inputting phone number to check for orders.
  • Caller inputting account name and password to query account balance.

Interface Development Specifications

When integrating with Udesk, third-party systems need to develop interfaces according to the following specifications.

Request Method

The interface must support the POST method. When Udesk requests the interface, request parameters will be placed in JSON format in the request body. The Content-Type of the request is application/json;charset=utf8.

Request Address

User-defined, but the protocol must be HTTPS or HTTP (meaning the interface address must start with https:// or http://), such as https://api.baidu.com/callcenter.

Request Parameter Description

The nested format of the request body is fixed as follows:


Explanation of each parameter:

Parameter NameParameter MeaningParameter Type
timestampUNIX timestampInteger
signAuthentication signatureString
dataValid dataHash
param1User-defined parameter 1String
udesk_force_node_idPreset parameter, identifies the smart routing node of the external interface commandString
udesk_call_idPreset parameter, unique identifier of the callString
udesk_from_numberPreset parameter, caller's numberString
udesk_to_numberPreset parameter, callee (i.e., relay number)String
udesk_call_start_timePreset parameter, time when the call was initiated, compliant with RFC 2616 specificationsString
udesk_mobile_areaPreset parameter, location of the caller's numberString

Request Example

POST https://api.baidu.com/callcenter

Content-Type: application/json;charset=utf8
Content-Length: 190

  "timestamp": 1501124998,
  "sign": "2f6e7e58c267ac3971770e991cb01239",
  "data": {
    "number": "18888888888",
    "param2": "233",
    "udesk_force_node_id": "1499446197778",
    "udesk_call_id": "2dbbae02-b18d-44eb-a343-3f53ff99dc96",
    "udesk_from_number": "18888888888",
    "udesk_to_number": "01001000000",
    "udesk_call_start_time": "Thu, 27 Jul 2017 05:52:53 GMT",
    "udesk_mobile_area": "Inner Mongolia, Hohhot"

Calculation Method for Signature (Sign)

Every company that opens a call center in Udesk has an authentication token, which is designed specifically for the call center to interface with external interfaces and serves no other purpose. The authentication token is in UUID format. Please contact Udesk's development engineer to obtain this token. Concatenate this token with the timestamp, then encrypt it with MD5 to obtain the signature value (sign).

The sign should only contain numbers and lowercase letters.

For example, if the token is "a3ddc2a2-58fa-42b4-8cb3-b40c9e0ff12a" and the timestamp is 1502879948, then the sign is MD5("a3ddc2a2-58fa-42b4-8cb3-b40c9e0ff12a1502879948"), which is "c70d665cc46dba4b71305172a0f826a2".

Response Format

The HTTP response returned by the interface should be in JSON format. The HTTP response body must contain the data field. Nested format of the return value:


Explanation of each parameter:

Parameter NameParameter MeaningParameter Type
dataValid dataHash
value_1User-defined response parameter 1String or Number or Boolean or other simple values
value_nUser-defined response parameter nString or Number or Boolean or other simple values

Response Example

  "data": {
    "code": 1

Interface Development Considerations

  1. In request parameters, besides carrying user-defined parameter information, it also includes some data that Udesk sets by default (i.e., parameters starting with udesk_). If these preset parameters can meet the requirements, there's no need to set custom request parameters.
  2. User-defined request parameters should not start with udesk_ to avoid duplication with preset parameters.
  3. The response value can only be simple types such as strings or numbers and does not support complex data structures like arrays or hashes, nor does it support multi-level nesting.
  4. When the response value is a string type, the maximum length should not exceed 255 characters. If it exceeds, Udesk only takes the first 255 characters.
  5. It is recommended to use simple integer enumeration values for response values, such as 0, 1, 2.
  6. The interface response time must be less than 3 seconds. When the interface time exceeds 3 seconds, it is considered a timeout request.

Usage Notes

Companies that need to integrate this interface must use the intelligent routing mode in the call center.