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:

timestamp
sign
data:
  param_1
  param_2
  param_n
  udesk_force_node_id
  udesk_call_id
  udesk_from_number
  udesk_to_number
  udesk_call_start_time
  udesk_mobile_area

Explanation of each parameter:

Parameter Name	Parameter Meaning	Parameter Type
timestamp	UNIX timestamp	Integer
sign	Authentication signature	String
data	Valid data	Hash
param1	User-defined parameter 1	String
udesk_force_node_id	Preset parameter, identifies the smart routing node of the external interface command	String
udesk_call_id	Preset parameter, unique identifier of the call	String
udesk_from_number	Preset parameter, caller's number	String
udesk_to_number	Preset parameter, callee (i.e., relay number)	String
udesk_call_start_time	Preset parameter, time when the call was initiated, compliant with RFC 2616 specifications	String
udesk_mobile_area	Preset parameter, location of the caller's number	String

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:

data:
  value_1
  value_2
  value_n

Explanation of each parameter:

Parameter Name	Parameter Meaning	Parameter Type
data	Valid data	Hash
value_1	User-defined response parameter 1	String or Number or Boolean or other simple values
value_n	User-defined response parameter n	String 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.