GET
/live/ws/live/connect请求头
Authorizationstring暂无说明
示例值:
Token vda_xxxQuery 参数
live_idstring必填，创建 live 返回的 live.id。
conn_idstring可选，客户端连接 ID；不传时服务端会生成。
返回结果
App WebSocket 用于初始化会话、发送文本、打断和挂断。它不传输音频或视频媒体。
json
{
"type": 1,
"live_id": "1234567890",
"user_id": "10000",
"conn_id": "app-conn-1",
"seq_id": 1,
"payload": {}
}type | 名称 | 方向 | 说明 |
|---|---|---|---|
`1` | `conn_init` | App → live | 连接初始化，必须在 WS 打开后发送。 |
`2` | `conn_init_ack` | live → App | 初始化结果。`success=true` 后表示实时控制链路 ready。 |
`5` | `call_hangup` | App → live | App 主动挂断。 |
`6` | `force_hangup` | live → App | 服务端强制挂断，例如超时、风控、积分不足或服务侧关闭。 |
`7` | `audio_interrupted` | App → live | 用户打断当前 AI 输出。 |
`99` | `text_msg` | App → live | 发送文本消息。 |
conn_init
conn_init_ack.success=false 时，error_code 的含义和处理建议统一见错误响应说明章节。本节仅保留请求、成功响应和失败响应示例。
text_msg
字段 | 说明 |
|---|---|
`msg_id` | 客户端生成的消息 ID，便于客户端日志关联。 |
`content` | 发送给数字人的文本内容。 |
`timestamp` | 客户端发送时间，毫秒时间戳。 |
当前服务端不会为 text_msg 单独返回业务 ack；数字人的回复通过 RTC 音视频输出，部分文本响应也可能从 WS 下发。
audio_interrupted
用于用户打断当前 AI 输出。当前没有单独 ack；客户端可结合后续音频停止、数字人响应变化或自身 UI 状态处理。
call_hangup 与 force_hangup
hangup_reason | 常见场景 |
|---|---|
`user_end` | 用户主动结束。 |
`timeout` | 会话达到最大时长。 |
`audit_violation` | 触发内容安全或风控策略。 |
`credit_insufficient` | 积分不足。 |
`sip_closed` / `provider_closed` | 服务侧或数字人渲染侧关闭。 |
`sip_reconnect_timeout` / `client_reconnect_timeout` | 断连超过重连宽限。 |
`external` | 后台或外部控制关闭。 |
除监听 type=6 外，客户端还必须监听 WebSocket close / error 事件做兜底。主动挂断后建议先关闭 WebSocket，再调用 RTC SDK 的 leaveChannel()。
5.6.5 session_update
用于在会话进行中（conn_init_ack success=true 之后）动态更新部分 session 配置，无需挂断重建会话。
- 更新按组传入：
avatar、vad、llm未传的字段保持原值； knowledge_retrieval/memory_retrieval为整组替换，传入即整体覆盖该组配置，组内未传的子字段按默认值处理。- 服务端整体校验本次更新，任一字段非法则本次更新失败，所有字段均不生效，原配置保持不变。
- 更新即时生效并作用于后续对话；
- 音色（voice）与人设（persona）若当前正在播报语音，将延迟至当前播报结束后生效，避免打断。更新不重新校验余额、不重置会话时长、不额外计费。
可更新字段与约束（沿用创建会话时的类型与范围；knowledge_retrieval / memory_retrieval 组内为整组替换，其余字段只传需要更新的部分）：
字段 | 类型 | 取值 / 约束 | 生效时机 | 非法处理 |
|---|---|---|---|---|
`avatar.voice` | String | 已有音色或克隆音色 ID | 当前播报结束后生效（无播报时立即） | 音色不存在 → 更新失败 |
`avatar.persona` | String | ≤ 5 万字 | 当前播报结束后生效（无播报时立即） | 超长 → 更新失败 |
`vad.type` | String | server / semantic | 下一轮 | 非枚举 → 拒绝 |
`vad.threshold` | float | \[0, 1.0\]，仅 type=server 生效 | 下一轮 | 越界 → 拒绝 |
`vad.silence_duration_ms` | int | \[200, 6000\] ms，仅 type=server 生效 | 下一轮 | 越界 → 拒绝 |
`knowledge_retrieval.enabled` | bool | true / false | 下一轮 | — |
`knowledge_retrieval.endpoint` | String | 可访问的 http(s) 绝对 URL，启用时必填 |
更新结果通过 session_update_ack 返回：
字段 | 说明 |
|---|---|
`success` | 本次更新是否被整体接受；为 false 时所有字段均不生效，原配置保持不变 |
`error_code / error_msg` | 失败错误码与原因（失败时返回，成功时为空） |