Udesk 即时通讯对话路由中支持在进行对话分配时中调用第三方系统的接口,根据接口的不同返回值执行不同的逻辑。

功能注意事项

为保证Udesk不受到本功能中调用第三方系统的影响,一旦在调用第三方系统时出现错误,那么本次对话将直接分配至公司队列! + 可能出现的错误有: - 第三方接口超时 - 第三方接口调用失败 - 第三方接口返回值不符合文档中规定

接口开发规范

第三方系统在与 Udesk 对接时,需要按照以下规范开发接口。

请求方法

Udesk将使用GET方法使用请求第三方系统接口

请求地址

用户自定义,但协议必须是 HTTPS,(即接口地址必须以 https://开头),如 https://api.baidu.com,否则请求将会失败并导致对话直接分配公司队列!

请求参数说明

用户自定义请求地址通过GET请求第三方系统前,Udesk还会在地址中添加鉴权的相关参数(后面会介绍鉴权的具体细节),则请求参数结构如下所示

参数名 取值类型 参数说明 备注
custom_parameter_1 Integer or String 用户自定义参数1 用户自定义参数仅支持纯字符串或者整数
custom_parameter_2 Integer or String 用户自定义参数2 用户自定义参数仅支持纯字符串或者整数
custom_parameter_n Integer or String 用户自定义参数n 用户的自定义参数无数量限制
udesk_customer_openid String 微信openid 系统参数
udesk_customer_unionid String 微信unionid系统参数 系统参数
udesk_customer_web_token String Web渠道客户唯一识别ID 系统参数
udesk_customer_sdk_token String SDK渠道客户唯一识别ID 系统参数
udesk_customer_customer_token String 系统唯一识别ID(跨渠道) 系统参数
sign String 签名 -
nonce String 6位随机字符串,用于计算签名 -
timestamp Integer Unix时间戳 -

请求地址示例:

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

鉴权说明

每一个在Udesk的公司都有唯一的open_api_token,首先请先获得该token(可在账户设置-安全设置-鉴权Token中取得)。 将token与参数中的noncetimestamp&连接起来,然后对拼接好的字符串进行SHA256散列,最后取得散列值的大写形式就得到了签名值 sign。

sign生成示例如下(ruby代码)

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

返回值结构说明

Udesk要求接口返回的响应应当为 JSON 格式。 返回值嵌套格式:

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

各参数说明:

参数名 取值类型 参数说明
value_1 String 或 Number 或 Boolean 等简单值 用户自定义响应参数1
value_2 String 或 Number 或 Boolean 等简单值 用户自定义响应参数2
value_n String 或 Number 或 Boolean 等简单值 用户自定义响应参数n

接口开发注意事项

  1. 请求参数中,用户自定义的参数信息不限制数量。
  2. 响应值只能为字符串或数字等简单类型值,不支持数组、哈希等复杂数据结构,不支持多层嵌套。
  3. 建议响应值取简单的整数枚举值,如 0、1、2。
  4. 接口响应时间必须小于200ms, 接口时间超过200ms时,视为请求超时。