Udesk instant messaging supports calling third-party system interfaces during conversation routing, and executing different logic based on the different return values of the interface.

Functional Notes

To ensure that Udesk is not affected by the invocation of third-party systems in this function, if an error occurs when calling a third-party system, the conversation will be directly assigned to the company's queue!

• Possible errors include:

• Timeout of the third-party interface
• Failure in calling the third-party interface
• The return value of the third-party interface does not comply with the specifications in the document

Interface Development Specifications

When the third-party system docks with Udesk, it needs to develop the interface according to the following specifications.

Request Method

Udesk will use the GET method to request the third-party system interface.

Request URL

User-defined, but the protocol must be HTTPS (i.e., the interface address must start with https://), such as https://api.baidu.com, otherwise the request will fail and the conversation will be directly assigned to the company's queue!

Request Parameter Explanation

Before using the GET method to request the third-party system, Udesk will also add related authentication parameters to the address (the authentication details will be introduced later), so the request parameter structure is as follows

Parameter Name	Data Type	Description	Remarks
custom_parameter_1	Integer or String	User-defined parameter 1	User-defined parameters only support pure strings or integers
custom_parameter_2	Integer or String	User-defined parameter 2	User-defined parameters only support pure strings or integers
custom_parameter_n	Integer or String	User-defined parameter n	User's custom parameters are unlimited in number
udesk_customer_openid	String	WeChat openid	System parameter
udesk_customer_unionid	String	WeChat unionid system parameter	System parameter
udesk_customer_web_token	String	Web channel customer unique identification ID	System parameter
udesk_customer_sdk_token	String	SDK channel customer unique identification ID	System parameter
udesk_customer_customer_token	String	System unique identification ID (cross-channel)	System parameter
sign	String	Signature	-
nonce	String	6-digit random string used to calculate the signature	-
timestamp	Integer	Unix timestamp	-

Request URL Example:

https://test.udesk.cn/?custom_parameter_1=params1&custom_parameter_2=params2&custom_parameter_n=paramsn&udesk_customer_openid=xxx&udesk_customer_unionid=xxx&udesk_customer_web_token=xxx&udesk_customer_sdk_token=xxx&udesk_customer_customer_token=xxx&&nonce=aff6fc&sign=59C5FD430525574B41EB456FBA44D6A8F22C8D9535CD33937FA8637E841BA76D&timestamp=1584931776

Authentication Explanation

Each company in Udesk has a unique open_api_token. First, please obtain this token (it can be obtained in Account Settings - Security Settings - Authentication Token). Concatenate the token with the parameters nonce and timestamp in the address with &, then hash the concatenated string using SHA256, and finally obtain the uppercase form of the hash value as the signature value sign.

Sign generation example (ruby code):

sign_str  = "#{open_api_token}&#{nonce}&#{timestamp}"
sign      = Digest::SHA256.hexdigest(sign_str).upcase

Response Structure Explanation

Udesk requires that the response returned by the interface be in JSON format. Nested return value format:

{
  "value_1": 1,
  "value_1": "value_2",
  "value_n": true
}

Parameter explanations:

Parameter Name	Data Type	Description
value_1	String or Number or Boolean	User-defined response parameter 1
value_2	String or Number or Boolean	User-defined response parameter 2
value_n	String or Number or Boolean	User-defined response parameter n

Interface Development Notes

1. In the request parameters, the user-defined parameter information is not limited in quantity.
2. The response value can only be a string or a number, etc., simple type value, does not support arrays, hashes, and other complex data structures, does not support multi-level nesting.
3. It is recommended to use simple integer enumeration values for response values, such as 0, 1, 2.
4. The interface response time must be less than `200ms

. If the interface time exceeds 200ms`, it will be considered as a timeout.