Udesk 呼叫中心支持在电话过程中调用第三方系统的接口，根据接口的不同返回值执行不同的逻辑。典型的应用场景有：

接口开发规范

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

请求方法

接口必须支持 POST 方法，Udesk 请求接口时，会将请求参数以 JSON 形式放在 request body 中，请求的 Content-Type 为 application/json;charset=utf8。

请求地址

用户自定义，但协议必须是 HTTPS 或 HTTP （即接口地址必须以 https:// 或 http:// 开头），如 https://api.baidu.com/callcenter

请求参数说明

request body 的嵌套格式固定如下：

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

各参数说明：

参数名称 参数含义 参数类型
timestamp UNIX 时间戳 Integer
sign 鉴权签名 String
data 有效数据 Hash
param1 用户自定义参数1 String
udesk_force_node_id 预置参数，此外部接口指令所在的智能路由节点标识 String
udesk_call_id 预置参数，该通话唯一标识 String
udesk_from_number 预置参数，主叫方号码 String
udesk_to_number 预置参数，被叫方（即中继号）号码 String
udesk_call_start_time 预置参数，主叫呼入时间，符合 RFC 2616 规范 String
udesk_mobile_area 预置参数，主叫号码归属地 String

请求示例

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": "内蒙古 呼和浩特市"
  }
}

签名 sign 的计算方法

每个在 Udesk 开通呼叫中心的公司都有一个认证 token，该 token 专为呼叫中心对接外部接口设计，不作他用。认证 token 为 UUID 格式，请联系 Udesk 研发工程师获得该 token。 将该 token 与 timestamp 拼接，再进行 MD5 加密，就得到签名值 sign。

sign 应当只包含数字和小写字母。

例如，token 为 "a3ddc2a2-58fa-42b4-8cb3-b40c9e0ff12a", timestamp 为 1502879948，则 sign 为 MD5("a3ddc2a2-58fa-42b4-8cb3-b40c9e0ff12a1502879948")，即 "c70d665cc46dba4b71305172a0f826a2" 。

响应格式

接口返回的HTTP响应应当为 JSON 格式。 HTTP response body 中必须有 data 字段。 返回值嵌套格式：

data:
  value_1
  value_2
  value_n

各参数说明：

参数名称 参数含义 参数类型
data 有效数据 Hash
value_1 用户自定义响应参数1 String 或 Number 或 Boolean 等简单值
value_n 用户自定义响应参数n String 或 Number 或 Boolean 等简单值

响应示例

{
  "data": {
    "code": 1
  }
}

接口开发注意事项

  1. 请求参数中，除了携带用户自定义的参数信息，还包含 Udesk 默认设置的一些数据（即以 udesk_ 开头的参数）。如果这些预置参数就能满足需求，可以不用设置自定义的请求参数。
  2. 用户自定义的请求参数不要以 udesk_ 开头，以避免与预置参数重复。
  3. 响应值只能为字符串或数字等简单类型值，不支持数组、哈希等复杂数据结构，不支持多层嵌套。
  4. 当响应值为字符串类型时，最大长度不宜超过 255 个字符。如果超过，Udesk 只取前 255 个字符。
  5. 建议响应值取简单的整数枚举值，如 0、1、2。
  6. 接口响应时间必须小于3s,接口时间超过3s时，视为请求超时。

使用须知

需要对接该接口的公司，呼叫中心必须使用智能路由模式。