序言
前面有读者反馈说，智能拨号器APP有没有办法在SIP协议之外，能让CRM后台远程推送号码过来进行打电话操作，以及话单录音在通话后推送到CRM的接口。
原先的做法是让用户的CRM连接到智能拨号器配套的阿里云服务器，然后它使用稳定的TCP连接将号码下发到智能拨号器APP。很明显，引入了中间环节，增加了服务器负担。并且从数据安全边界的角度而言也不合适。
由此，智能拨号器APP在电话语音拦截的基础之上，于APP设置中增加了配置外部第三方WebSocket稳定连接的能力，供第三方CRM直接跟手机APP进行数据交互。
体验和下载地址：
智能拨号器App： http://120.78.211.195:8060/Dialer.apk
智能拨号器APP
外部WebSocket话单推送系统接口文档
1. 概述
本系统用于实现服务端（C#/Java/Node.js 等）与 Android 客户端之间的实时话单推送、通话控制及录音文件上传功能。
WebSocket 负责实时双向消息传递（命令下发、状态上报、话单推送）。
HTTP 负责录音文件及 ASR 文本文件的上传。
服务端需要同时提供：
1）WebSocket 服务（维持长连接，用于下发号码进行外呼，以及话单返回）
2）HTTP 文件上传服务（用于录音和ASR通话内容文本的推送）
基础 URL：
WebSocket：示例ws://120.78.211.195:8070/json
HTTP 上传：http://120.78.211.195:8071/upload/
2. 交互流程概览
3. WebSocket 接口列表
3.1 客户端 → 服务端
|----------|-----|-----------|---------------------------------------|
| 命令 (cmd) | 方向 | 说明 | 必填字段 |
| REGISTER | C→S | 客户端注册身份 | userName, deviceId, timestamp |
| STATUS | C→S | 上报通话忙碌状态 | isBusy (bool) |
| CALL_END | C→S | 挂断并上报话单 | sessionId, phone, duration, recordUrl |
| ping | C→S | 心跳请求（纯文本） | 无 |
3.2 服务端 → 客户端
|---------------|-----|-----------|----------------------------|
| 命令 (cmd) | 方向 | 说明 | 字段 |
| REGISTER_RESP | S→C | 注册响应 | status, message, uploadUrl |
| CALL | S→C | 主动下发呼叫指令 | phone, sessionId, sim(可选) |
| STATUS_RESP | S→C | 状态上报响应 | status |
| CALL_END_RESP | S→C | 话单上报响应 | status |
| ERROR | S→C | 错误响应 | message |
| pong | S→C | 心跳响应（纯文本） | 无 |
4. JSON 消息格式（平铺，无 data 封装）
4.1 REGISTER（客户端→服务端）
json
{ "cmd": "REGISTER", "userName": "张三", "deviceId": "device_123456", "timestamp": 1700000000000}
4.2 REGISTER_RESP（服务端→客户端）
json
{ "cmd": "REGISTER_RESP", "status": "ok", "message": "注册成功", "uploadUrl": "http://192.168.31.240:8071/upload/"}
uploadUrl 后续用于 HTTP 文件上传。
4.3 STATUS（客户端→服务端）
json
{ "cmd": "STATUS", "isBusy": true}
通话开始时发 true，挂断后发 false。
4.4 STATUS_RESP（服务端→客户端）
json
{ "cmd": "STATUS_RESP", "status": "ok"}
4.5 CALL（服务端→客户端）
json
{ "cmd": "CALL", "phone": "10086", "sessionId": "uuid-xxxx", "sim": "sim1" // 可选 }
4.6 CALL_END（客户端→服务端）
json
{ "cmd": "CALL_END", "sessionId": "uuid-xxxx", "phone": "10086", "duration": 120, "recordUrl": "http://192.168.31.240:8070/recordings/10086_20260822015445.mp3", "aiLevelId": 3, // 可选 "aiLevelName": "优秀" // 可选 }
4.7 CALL_END_RESP（服务端→客户端）
json
{ "cmd": "CALL_END_RESP", "status": "ok"}
4.8 ERROR（服务端→客户端）
json
{ "cmd": "ERROR", "message": "注册失败: 用户名已存在"}
5. HTTP 文件上传接口
URL ：POST {uploadUrl}（例如 http://192.168.31.240:8071/upload/）
Content-Type ：multipart/form-data
字段说明 ：
|--------------|--------|----|----------------------------------------|
| 字段名 | 类型 | 必填 | 说明 |
| baseFileName | string | 是 | 录音文件名，如 10086_20260822015445.mp3 |
| sessionId | string | 是 | 关联会话ID（可与baseFileName一致） |
| audioFile | file | 是 | 录音文件（.mp3/.wav等） |
| farTextFile | file | 否 | 麦克风注入的ASR文本文件，命名为 {baseFileName}.0.txt |
| nearTextFile | file | 否 | 对方说话的ASR文本文件，命名为 {baseFileName}.1.txt |
响应 （成功，HTTP 200）：
json
{ "url": "http://192.168.31.240:8070/recordings/10086_20260822015445.mp3"}
此 URL 即为客户端在 CALL_END 中需填入的 recordUrl。
响应 （失败，HTTP 4xx/5xx）：
返回纯文本错误信息（如 "No audio file uploaded"）或 JSON 格式错误（根据服务端实现）。
6. 心跳机制
客户端每隔 30 秒 发送一次纯文本 "ping"。
服务端收到后必须回复纯文本 "pong"。
若服务端超时未收到 ping，可主动关闭连接；若客户端未收到 pong，应触发重连逻辑。
7. 错误处理与重连
注册超时 ：服务端应在客户端连接后 10 秒内收到 REGISTER，否则主动关闭连接（防攻击）。
消息频率限制 ：服务端可限制每分钟最多 60 条消息，超出回复 ERROR 并断开。
客户端重连 ：当 WebSocket 异常断开时，客户端应自动重连（指数退避，初始 5 秒，最大 30 秒）。
重连后需重新发送 REGISTER，服务端应重新下发 uploadUrl。
8. 服务端实现注意事项
WebSocket 服务路径 ：务必保持长连接，否则手机智能拨号器APP无法接收到下发的外呼电话号码。
HTTP 上传服务路径 ：http和https均可以，用于接收电话通话的录音文件，以及智能拨号器APP对通话双方做的ASR通话文字内容文件。
文件存储目录 ：建议自行将话单和录音做持久化存储，符合各方面的等保要求，确保写权限。
录音文件访问 URL ：返回的 url 应提供 HTTP 静态文件服务（如使用 Nginx 或内置静态服务器）。
安全性 ：
内网环境可忽略证书，公网建议使用 wss:// 和 https://。
可增加 Token 校验（如注册时携带密钥）。
并发 ：服务端需支持多个客户端同时连接，每个客户端对应一个手机中智能拨号器应用APP。
9. 示例交互（正常流程）
客户端 → ws://ip:8070/call
客户端 → {"cmd":"REGISTER","userName":"admin","deviceId":"abc","timestamp":...}
服务端 → {"cmd":"REGISTER_RESP","status":"ok","message":"注册成功","uploadUrl":"http://ip:8071/upload/"}
每 30 秒 ping ↔ pong
服务端 → {"cmd":"CALL","phone":"10086","sessionId":"sess-001"}
客户端 → {"cmd":"STATUS","isBusy":true}
通话结束，客户端上传 audioFile、farTextFile、nearTextFile 到 http://ip:8071/upload/
HTTP 服务端 → {"url":"http://ip:8070/recordings/10086_20260822015445.mp3"}
客户端 → {"cmd":"CALL_END","sessionId":"sess-001","phone":"10086","duration":30,
"recordUrl":"http://ip:8070/recordings/10086_20260822015445.mp3"}
服务端 → {"cmd":"CALL_END_RESP","status":"ok"}
客户端 → {"cmd":"STATUS","isBusy":false}
10. 版本历史
|------|------------|----------------|
| 版本 | 日期 | 修改内容 |
| v1.0 | 2026-07-23 | 初始版本，基于当前实现整理。 |
文档结束。 如有疑问，请联系开发团队。