1. 概述

本接口支持客户端通过 WebSocket 协议接入百融百语的语音对话服务，实现与 AI Agent 的实时语音交互。客户端需按照本文档规定的流程与格式进行通信。使用 API 之前参考《语音通话接入准备工作》获取 robotKey 和 robotToken。

2. 接入地址

生产环境: wss://baiyu.resultscloud.com/api/realtime/calls/v1/dialog

3. 连接参数（URL Query）

建立 WebSocket 连接时，需在 URL 中携带以下查询参数：

参数名	必选	说明
`robotKey`	是	API 密钥标识，需进行 URL 转义（如在 Node.js 中用 `encodeURIComponent()` 处理）。
`robotToken`	是	API 密钥 Token。
`client`	否	客户端类型。可选值：`twilio`（默认），其他类型待后续扩展。
`userName`	否	接入者标识，用于查询历史对话记录。

示例连接 URL：

wss://baiyu.resultscloud.com/api/realtime/calls/v1/dialog?robotKey=yourKey&robotToken=yourToken

特别注意：系统生成的 robotKey 中带有百分号，在 URL 中拼接字符串需要手动做转义处理。如 js 编程语言中用 encodeURIComponent() 方法进行转义。

4. 交互流程

建立连接：客户端发起 WebSocket 连接，并在 URL 中携带鉴权参数。
启动会话：连接成功后，客户端必须立即发送 start 事件，用于声明音频格式及会话参数。
媒体传输：服务端接收 start 事件后进入就绪状态，双方开始通过 media 事件双向传输音频流。
事件消息：通话过程中，服务端会推送 message 事件，包含文本转录事件、情绪识别事件和服务端挂断事件。
客户端主动打断：在通话过程中，客户端可发送 interrupt 事件以打断 Agent 当前的语音输出。

5. 事件定义

所有交互事件均以 JSON 格式通过 WebSocket 的 Text 帧 进行传输。 通用字段说明：

字段	类型	描述
`event`	`string`	事件类型，详见下文各小节。
`sequenceNumber`	`string`	事件序列号，从 `"0"` 开始严格递增（`clear` 等特殊事件除外）。
`streamSid`	`string`	流会话唯一标识符，由客户端在 `start` 事件中指定或由服务端生成。

5.1 客户端 → 服务端事件

5.1.1 start - 启动通话

连接建立后必须立即发送的首条消息，用于配置音频会话参数。 事件示例：

{
    "event": "start",
    "sequenceNumber": "0",
    "streamSid": "",
    "start": {
        "accountSid": "",
        "streamSid": "",
        "callSid": "",
        "tracks": [
            "inbound", "outbound"
        ],
        "mediaFormat": {
            "encoding": "audio/pcm16",
            "sampleRate": 16000,
            "channels": 1,
            "sourceFrom": "sip"
        },
        "customParameters": {
            "phoneNumber": "18874920315",
            "customVariables": {
              "variableA": "username",
              "variableB": 12312312,
            }
        }
    }
}

start 对象字段说明：

字段	类型	必选	描述
`accountSid`	`string`	否	账户标识，留空即可。
`streamSid`	`string`	否	流标识，若留空则由服务端生成。
`callSid`	`string`	否	通话标识，用于业务记录。
`tracks`	`array`	是	音频轨道方向，固定值：`["inbound", "outbound"]`。
`mediaFormat.encoding`	`string`	是	音频编码格式。可选值： - `audio/pcm16` (16kHz, 16bit 小端序) - `audio/x-mulaw` (8kHz, μ-law) - `audio/x-alaw` (8kHz, A-law)
`mediaFormat.sampleRate`	`int`	是	采样率。需与 `encoding` 对应： - `audio/pcm16` → `16000` - `audio/x-mulaw` / `audio/x-alaw` → `8000`
`mediaFormat.channels`	`int`	是	声道数，当前固定为 `1`。
`mediaFormat.sourceFrom`	`string`	否	音源类型。`sip`（默认）或 `web`，用于调整前端识别灵敏度。
`customParameters.phoneNumber`	`string`	否	主叫号码，用于日志记录与溯源。
`customParameters.customVariables`	`object`	否	此对象下的 key-value 为用户自定义变量。

5.1.2 media - 发送音频数据

用于将客户端采集并编码后的用户语音流发送至服务端。 事件示例：

{
    "event": "media",
    "sequenceNumber": "1",
    "streamSid": "CustomStreamId",
    "media": {
        "track": "inbound",
        "chunk": "1",
        "timestamp": "1756567741474",
        "payload": "base64EncodedAudioDataHere"
    }
}

media 对象字段说明：

字段	类型	描述
`media.track`	`string`	音频方向，客户端上行固定为 `"inbound"`。
`media.chunk`	`string`	音频数据块序号，建议递增。
`media.timestamp`	`string`	Unix 毫秒时间戳。
`media.payload`	`string`	Base64 编码的音频数据。

5.1.3 interrupt - 打断事件

当用户希望终止当前播放时，客户端可主动发送此指令。 事件示例：

{
    "event": "interrupt",
    "sequenceNumber": "2",
    "streamSid": "CustomStreamId",
    "interrupt": {
        "reason": "user_interrupt",
        "accountSid": "",
        "callSid": ""
    }
}

5.2 服务端 → 客户端事件

5.2.1 media - 下发 Agent 音频

服务端将 AI Agent 合成的语音流推送至客户端。 事件示例：

{
    "event": "media",
    "sequenceNumber": "100",
    "streamSid": "TR_xxx",
    "media": {
        "track": "outbound",
        "chunk": "1",
        "timestamp": "1756567742000",
        "payload": "base64EncodedAudioDataHere"
    }
}

注意：media.track 固定值为 "outbound"。

5.2.2 message - 复合消息事件

message 事件是复合了多种消息类型的事件，包含：

交互文本事件：服务端识别用户语音为文本的结果（包含中间结果）及 Agent 响应的文本结果；
附带信息响应事件：如性别、年龄、情绪等附带信息；
交互终止事件：指示服务端错误或命中终止规则而导致会话终止的事件。

事件示例：

{
    "event": "message",
    "sequenceNumber": "3469",
    "streamSid": "web-stream-1780301127600",
    "message": {
        "code": 0,
        "mimeType": "",
        "id": "chat_127_0",
        "topic": "chat",
        "timestamp": 0,
        "role": "user",
        "final": false,
        ... // 省略部分可变字段
    }
}

字段说明：

字段	类型	描述
`code`	`int`	状态码，`0` 表示成功。
`errMsg`	`string`	错误信息描述。
`id`	`string`	事件唯一标识符。
`mimeType`	`string`	内容类型，固定为 `text/plain`。
`topic`	`string`	事件子分类，`chat`、`side_info` 或 `interrupt`。
`timestamp`	`number`	Unix 毫秒时间戳。
`role`	`string`	说话人角色： - `"user"`：用户语音识别结果。 - `"llm"`：AI Agent 回复文本。
`final`	`boolean`	是否为最终结果： - `false`：中间增量结果。 - `true`：该句最终完整文本。
`payload`	`object`	扩展信息对象，包含 `gender`、`age`、`emotion` 等属性分析结果。
`encryptionType`	`int`	加密类型标识，通常为 `0`。
`text`	`string`	当前识别或回复的文本片段。

5.2.2.1 交互文本事件（message.topic: chat）

交互文本事件中包含服务端识别的用户语音为文本的结果（包含中间结果）或 AI Agent 的文本回复结果。 事件示例：

{
    "event": "message",
    "sequenceNumber": "3469",
    "streamSid": "web-stream-1780301127600",
    "message": {
        "code": 0,
        "mimeType": "",
        "timestamp": 0,
        "role": "user",
        "topic": "chat",
        "id": "chat_127_0",
        "text": "哎，那个闲",
        "final": false
    }
}

字段说明（事件内通用字段见上，不再赘述）：

字段	类型	描述
`message.role`	`string`	`user` 或 `llm`，分别对应用户和 AI Agent。
`message.text`	`string`	`role` 对应的文本消息内容。

5.2.2.2 附带信息事件（message.topic: side_info）

附带信息当前有对用户性别、年龄、情绪的判断。 事件示例：

{
    "event": "message",
    "sequenceNumber": "283",
    "streamSid": "web-stream-1780301127600",
    "message": {
        "code": 0,
        "mimeType": "",
        "timestamp": 0,
        "role": "user",
        "topic": "side_info",
        "id": "chat_3_0",
        "payload": {
            "chat_id": 3,
            "transcript": "你能做什么？",
            "gender": "男性",
            "age": "20–40岁",
            "emotion": "质疑"
        },
        "final": true
    }
}

字段说明（事件内通用字段见上，不再赘述）：

字段	类型	描述
`message.payload.chat_id`	`int`	消息 ID。
`message.payload.transcript`	`string`	对应的用户文本内容。
`message.payload.gender`	`string`	识别出的性别。
`message.payload.age`	`string`	识别出的年龄。
`message.payload.emotion`	`string`	识别出的情绪。

5.2.2.3 服务端挂断事件（message.topic: interrupt）

在服务端遇到错误（包含错误配置）或命中终止条件时，服务端会返回挂断事件。挂断事件中 code 可用于判别挂断原因，部分 code 如下：

900007: 触发挂断策略关键字（在“实时互动配置”-“挂断策略”处设置）
900008: 触发封控敏感词（涉恐、涉黄、涉暴）

事件示例：

{
    "event": "message",
    "sequenceNumber": "630",
    "streamSid": "web-stream-1780301127600",
    "message": {
        "code": 900007,
        "errMsg": "internal info: terminal sentence",
        "mimeType": "",
        "timestamp": 0,
        "role": "llm",
        "topic": "interrupt",
        "id": "chatID_interrupt",
        "text": "再见",
        "final": true
    }
}

字段	类型	描述
`message.text`	`string`	触发挂断的关键字。

6. 音频格式处理说明

服务端会对音频流进行自适应转码，以适配 ASR（语音识别）引擎要求。

客户端声明格式	服务端上行处理逻辑（客户端 → 服务端）	服务端下行处理逻辑（服务端 → 客户端）
`audio/pcm16` + `16000`	直接透传，无需转码。	直接透传 16kHz PCM16 音频。
`audio/x-mulaw` + `8000`	μ-law 解码 → 重采样至 16kHz → 送入 ASR。	16kHz 音频降采样至 8kHz → μ-law 编码下发。
`audio/x-alaw` + `8000`	A-law 解码 → 重采样至 16kHz → 送入 ASR。	16kHz 音频降采样至 8kHz → A-law 编码下发。

7. 连接生命周期与错误处理

启动超时：连接建立后若 300 秒内未收到 start 事件，服务端将主动断开连接。

语音agent

RTC

WebSocket

Realtime WebSocket API 接入文档

1. 概述

2. 接入地址

3. 连接参数（URL Query）

4. 交互流程

5. 事件定义

5.1 客户端 → 服务端事件

5.1.1 start - 启动通话

5.1.2 media - 发送音频数据

5.1.3 interrupt - 打断事件

5.2 服务端 → 客户端事件

5.2.1 media - 下发 Agent 音频

5.2.2 message - 复合消息事件

5.2.2.1 交互文本事件（message.topic: chat）

5.2.2.2 附带信息事件（message.topic: side_info）

5.2.2.3 服务端挂断事件（message.topic: interrupt）

6. 音频格式处理说明

7. 连接生命周期与错误处理

语音agent

RTC

WebSocket

​1. 概述

​2. 接入地址

​3. 连接参数（URL Query）

​4. 交互流程

​5. 事件定义

​5.1 客户端 → 服务端事件

​5.1.1 start - 启动通话

​5.1.2 media - 发送音频数据

​5.1.3 interrupt - 打断事件

​5.2 服务端 → 客户端事件

​5.2.1 media - 下发 Agent 音频

​5.2.2 message - 复合消息事件

​5.2.2.1 交互文本事件（message.topic: chat）

​5.2.2.2 附带信息事件（message.topic: side_info）

​5.2.2.3 服务端挂断事件（message.topic: interrupt）

​6. 音频格式处理说明

​7. 连接生命周期与错误处理

1. 概述

2. 接入地址

3. 连接参数（URL Query）

4. 交互流程

5. 事件定义

5.1 客户端 → 服务端事件

5.1.1 start - 启动通话

5.1.2 media - 发送音频数据

5.1.3 interrupt - 打断事件

5.2 服务端 → 客户端事件

5.2.1 media - 下发 Agent 音频

5.2.2 message - 复合消息事件

5.2.2.1 交互文本事件（message.topic: chat）

5.2.2.2 附带信息事件（message.topic: side_info）

5.2.2.3 服务端挂断事件（message.topic: interrupt）

6. 音频格式处理说明

7. 连接生命周期与错误处理