WebSocket 外呼系统接口文档

版本号：V1.0
编制日期：2026年

一、文档基本信息

项目	内容
接口协议	WebSocket（ws）
连接鉴权	Bearer Token（请求头方式）
数据传输格式	JSON
音频编码规范	PCM16、8K采样率、Base64编码
核心会话标识	sessionId（每次通话唯一，通话标识）

二、基础连接规范

2.1 连接地址

客户端通过 WebSocket 协议连接服务端：

wss://{服务器域名}/ws

注：实际连接地址由服务端分配

2.2 连接请求头

连接时必须携带 Bearer Token：

{
  "Authorization": "Bearer {服务端颁发的AUTH_TOKEN}"
}

注：Token 需妥善保管

三、客户端主动发送指令（C -> S）

所有请求均为 JSON 格式：

{
  "type": "",
  "sessionId": "通话id",
  "requestId": "请求id",
  "userId":"坐席id"
  "content": {}
}

3.1 发起外呼（call）

作用：发起通话,当发起呼叫时，sessionId不传,根据callState 事件返回的sessionId 确定每次的通话id

{
  "type": "call",
  "requestId": "",
  "userId":""
  "content": {
    "callee": "07518999_13000000000",
  }
}

字段说明

userId：坐席id

callee：主叫_被叫

3.2 主动挂断（hangup）

{
  "type": "hangup",
  "sessionId": "通话id",
  "requestId": "",
  "userId":""
  "content": ""
}

3.3 发送音频流（audioAppend）

{
  "type": "audioAppend",
  "sessionId": "通话id",
  "requestId": "",
  "userId":""
  "content": {
    "sampleRate": 8000,
    "delta": "Base64音频数据"
  }
}

关键说明

delta：PCM16 + 8K + Base64

3.4 在线保持（ping）

{
  "type": "ping",
  "requestId": "",
  "userId":""
  "content": "
}

四、服务端推送（S -> C）

4.1 通话状态（callState）

{
  "type": "callState",
  "sessionId": "通话id",
  "requestId": "",
  "userId":""
  "content": {
    "state": 1,
    "stateText": "呼叫中",
    "sipCode": 100,
    "sipCodeText": "Trying"
  }
}

状态码

状态码	状态	含义
1	呼叫中	已发起
3	响铃	等待接听
5	接通	可发音频
6	结束	通话结束

4.2 接收音频（audioDelta）

{
  "type": "audioDelta",
  "sessionId": "会话ID",
  "requestId": "",
  "userId":""
  "content": {
    "delta": "Base64音频数据"
  }
}

五、通用字段说明

字段	类型	含义	是否必填
type	string	类型标识	必填
sessionId	string	会话ID	必填
requestId	string	请求ID	可空
content	any	业务内容	按场景

六、异常处理规范

6.1 音频异常

Base64 解码失败 → 忽略

非 PCM16/8K → 忽略

6.2 会话异常

非当前 sessionId → 丢弃

6.3 状态异常

state=6 后禁止：

audioAppend

hangup

七、开发注意事项

sessionId 必须唯一（建议 UUID）

音频必须：

PCM16

8K采样率

Base64

必须在 state=5 后发送音频

state=6 后：

释放资源

Token 不要硬编码

必须实现超时机制

八、典型流程（建议实现）

连接 → 鉴权 → call
          ↓
     callState(1/3)
          ↓
     callState(5) → 发送音频
          ↓
     audioDelta（接收音频）
          ↓
     callState(6) → 清理资源

WebSocket 外呼系统接口文档

WebSocket 外呼系统接口文档#

一、文档基本信息#

二、基础连接规范#

2.1 连接地址#

2.2 连接请求头#

三、客户端主动发送指令（C -> S）#

3.1 发起外呼（call）#

字段说明#

3.2 主动挂断（hangup）#

3.3 发送音频流（audioAppend）#

关键说明#

3.4 在线保持（ping）#

四、服务端推送（S -> C）#

4.1 通话状态（callState）#

状态码#

4.2 接收音频（audioDelta）#

五、通用字段说明#

六、异常处理规范#

6.1 音频异常#

6.2 会话异常#

6.3 状态异常#

七、开发注意事项#

八、典型流程（建议实现）#

WebSocket 外呼系统接口文档

一、文档基本信息

二、基础连接规范

2.1 连接地址

2.2 连接请求头

三、客户端主动发送指令（C -> S）

3.1 发起外呼（call）

字段说明

3.2 主动挂断（hangup）

3.3 发送音频流（audioAppend）

关键说明

3.4 在线保持（ping）

四、服务端推送（S -> C）

4.1 通话状态（callState）

状态码

4.2 接收音频（audioDelta）

五、通用字段说明

六、异常处理规范

6.1 音频异常

6.2 会话异常

6.3 状态异常

七、开发注意事项

八、典型流程（建议实现）