的卢通信对接 - 需求文档

1.1 功能目标

在现有对接中心基础上，新增"旳卢通信"呼叫中心平台对接，实现：

• CRM直接外呼拨打电话，唤醒对接好的旳卢通信平台
• 把旳卢通信的电话量、电话录音、拨打数量同步到系统客户资料联系记录中
• 尽可能保持扩展性，为以后添加其他平台准备

1.2 涉及项目

项目	路径	说明
APP端	/Users/eric/Work/AndroidStudioProjects/XKW/xkw-dial	Android客户端
WEB端	/Users/eric/Work/AndroidStudioProjects/XKW/wp-client	Vue前端
后端	/Users/eric/Work/AndroidStudioProjects/XKW/wp-api	Go后端服务

1.3 的卢通信API参考

文档	URL	说明
的卢通信文档	https://www.kdocs.cn/l/ch9kXR1UvoN2	的卢通信API文档

2.1 接口一览

接口名称	方法	路径	改动类型	说明
获取对接类型列表	GET	/action/device/docking/getDockingType	修改	返回列表增加"的卢通信"选项
编辑对接详情	POST	/action/device/docking/editDockingDetail	修改	支持保存的卢通信配置
外呼接口	POST	/action/device/docking/callPhone	修改	支持旳卢通信外呼
通话记录	GET	/action/device/call	GET	已有，需确认是否改动
动态列表	GET	/action/common/getDynamicList	GET	已有，需确认是否改动

2.2 获取对接类型列表

响应数据结构：

{
  "code": 1,
  "data": [
    {
      "callCfgId": "配置ID",
      "callMethodName": "回呼",
      "callMethod": 1,
      "platId": "平台ID",
      "platName": "极简互联",
      "platLogo": "https://xxx/logo.png",
      "config": { ... },
      "is_default": true
    },
    {
      "platId": "delu",
      "platName": "的卢通信",
      "platLogo": "https://xxx/delu.png",
      ...
    }
  ]
}

2.3 编辑对接详情

请求参数：

{
  "id": "员工当前配置id",
  "fields": [
    { "key": "appid", "value": "AppId" },
    { "key": "appsecret", "value": "秘钥" },
    { "key": "serverUrl", "value": "服务器地址" }
  ],
  "plant_form_id": "delu",
  "call_cfg_id": "呼叫方式配置ID",
  "default_status": 2
}

2.4 外呼接口

请求参数：

{
  "platform_id": "delu",
  "call_cfg_id": "呼叫方式配置ID",
  "user_id": "员工ID",
  "to": "被叫号码",
  "cid": "客户ID"
}

3.1 接口一览

接口名称	方法	路径	改动类型	说明
获取外呼方式列表	GET	/action/crm/callModKV	修改	返回列表增加"的卢通信"选项
发起外呼请求	POST	/action/crm/callPhone	修改	支持的卢通信外呼

3.2 获取外呼方式列表

响应数据结构：

{
  "success": true,
  "result": [
    { "_id": "xxx", "name": "回呼" },
    { "_id": "yyy", "name": "小号" },
    { "_id": "delu", "name": "的卢通信" }
  ]
}

3.3 发起外呼请求

请求参数：

{
  "callTypeId": "delu",
  "cid": "customer_001",
  "phone": "13812345678",
  "isEncrypt": false
}

4.1 接口一览

接口名称	方法	路径	改动类型	说明
获取对接类型	GET	/action/device/docking/getDockingType	修改	返回列表增加"的卢通信"选项
外呼	POST	/action/device/docking/callPhone	修改	调用旳卢通信外呼API
编辑对接详情	POST	/action/device/docking/editDockingDetail	修改	保存旳卢通信配置
通话记录	POST	/action/device/call	GET	已有，需同步旳卢通信通话记录
动态列表	POST	/action/common/getDynamicList	GET	已有，需包含旳卢通信通话

4.2 获取对接类型列表

文件位置：handler/action/docking/controller.go

4.3 外呼接口

改动说明：

• 当 PlatformId = "delu" 时，调用旳卢通信外呼API（回拨模式）
• 旳卢通信外呼接口：POST https://crmapp.dilukeji.cn/api/app/bind

4.4 通话记录同步

改动说明：

• 当 platform_id = "delu" 时，从旳卢通信拉取通话记录
• 或通过回调地址接收旳卢通信推送的通话记录

4.5 动态列表（联系记录）

改动说明：

• logType 增加 "callDelu" 用于区分旳卢通信通话

5.1 签名算法

所有POST参数merge形成Key-Value形式的待签名数组（不包含sign参数）

• 将参数数组根据key做正向排序
• 用 key1=value1&key2=value2 形式拼接
• 值为空字符串或null不参与签名，key需要小写
• 最后拼接 &appsecret=秘钥字符串
• 计算整个字符串的MD5值，即为sign的值

示例：

sign=MD5(a=1&b=2&c=3&appsecret=sdfjhweu2345oiy4iu3234t4dgg)

5.2 拨打接口（回拨模式）

URL：POST https://crmapp.dilukeji.cn/api/app/bind

Content-Type：application/json

模式说明：员工拨打平台，平台代呼被叫；客户看到平台中间号，员工手机号不需加白。

参数	类型	必填	说明
appid	String	是	的卢提供
caller	String	是	主叫，员工手机号
callee	String	是	被叫，客户的手机号
callback_url	String	否	话单回调地址，不填则使用后台配置的默认地址
sign	String	是	签名（小写32位MD5）

请求示例：

{
  "appid": "123456",
  "caller": "13516622933",
  "callee": "136044242187",
  "callback_url": "https://www.xx.com/callback",
  "sign": "abc123ggouim3ff"
}

成功响应：

{
  "code": 10000,
  "msg": "绑定成功",
  "data": {
    "sessionId": "1000037366111982",
    "telX": "1318***739"
  }
}

响应参数说明：

参数	类型	说明
sessionId	String	话单唯一标识ID，用于判断呼叫是否成功
telX	String	平台分配的中间号

5.3 话单推送回调

推送方式：POST

说明：callback_url 可在的卢通信管理后台配置，也可通过请求参数传入。不填写则使用后台配置的默认地址。

{
  "session_id": "1000037366111982",
  "bind_num": "130***924",
  "caller_num": "166***945",
  "callee_num": "139***386",
  "fwd_start_time": "2021-06-18 16:31:49",
  "call_end_time": "2021-06-18 16:31:49",
  "billsec": 0,
  "status": 0,
  "record_flag": 0,
  "record_file_download_url": "https://www.xx.com/xxx.mp3"
}

回调参数说明：

参数	类型	说明
session_id	String	话单id
bind_num	String	中间号
caller_num	String	主叫号码
callee_num	String	被叫号码
fwd_start_time	String	外呼开始时间
call_end_time	String	通话结束时间
status	int	通话状态：1-接通，0-未接通，-1-接通失败
billsec	String	通话时长(秒)
record_flag	String	录音状态：0-未接通不生成录音，1-已接通
record_file_download_url	String	预生成录音地址（生成延迟10分钟-24小时）

注意：回调地址返回 code 不为 0 时，将继续推送直到 3 次；若 3 次皆失败，该条回调停止推送。可通过 sessionId 查询接口获取话单。

6.1 对接中心列表页

功能：显示所有可对接的呼叫中心平台

• 标题：对接中心
• 新增"的卢通信"卡片
• 平台来源显示：显示各平台的标识（如"旳卢通信"标识）

6.2 呼叫方式配置页

表单字段：

字段	必填	说明
appid	是	的卢通信提供的AppId
appsecret	是	的卢通信提供的秘钥
服务器地址	否	的卢通信 API 地址（默认：https://crmapp.dilukeji.cn）
主叫号码	是	员工手机号（回拨模式不需加白）

7.1 平台配置表

{
  "platId": "delu",
  "platName": "的卢通信",
  "apiBaseUrl": "https://crmapp.dilukeji.cn",
  "signType": "md5",
  "fields": [
    { "key": "appid", "label": "AppId", "required": true },
    { "key": "appsecret", "label": "秘钥", "required": true }
  ]
}

7.2 员工呼叫配置

{
  "_id": "配置ID",
  "user_id": "员工ID",
  "platform_type": "delu",
  "fields": {
    "appid": "AppId",
    "appsecret": "加密秘钥",
    "caller": "员工手机号",
    "serverUrl": "https://crmapp.dilukeji.cn"
  }
}