呼叫中心智能路由外部接口

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

接口开发规范

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

请求方法

接口必须支持 POST 方法,Udesk 请求接口时,会将请求参数以 JSON 形式放在 request body 中,请求的 Content-Typeapplication/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",
    "udsek_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时,视为请求超时。

使用须知

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