Enhance WebSocket session management by requiring assistant_id as a query parameter for connection. Update API reference documentation to reflect changes in message flow and metadata validation rules, including the introduction of whitelists for allowed metadata fields and restrictions on sensitive keys. Refactor client examples to align with the new session initiation process.
This commit is contained in:
Xin Wang
@@ -11,9 +11,11 @@ WebSocket 端点提供双向实时语音对话能力，支持音频流输入输
|
||||
### 连接地址
|
||||
|
||||
```
|
||||
ws://<host>/ws
|
||||
ws://<host>/ws?assistant_id=<assistant_id>
|
||||
```
|
||||
|
||||
- `assistant_id` 为必填 query 参数，用于从数据库加载该助手的运行时配置。
|
||||
|
||||
### 传输规则
|
||||
|
||||
- **文本帧**：JSON 格式控制消息
|
||||
@@ -25,8 +27,6 @@ ws://<host>/ws
|
||||
### 消息流程
|
||||
|
||||
```
|
||||
Client -> hello
|
||||
Server <- hello.ack
|
||||
Client -> session.start
|
||||
Server <- session.started
|
||||
Server <- config.resolved
|
||||
@@ -44,27 +44,9 @@ Server <- session.stopped
|
||||
|
||||
### 客户端 -> 服务端消息
|
||||
|
||||
#### 1. Handshake: `hello`
|
||||
#### 1. Session Start: `session.start`
|
||||
|
||||
客户端连接后发送的第一个消息，用于协议版本协商。
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "hello",
|
||||
"version": "v1"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `type` | string | 是 | 固定为 `"hello"` |
|
||||
| `version` | string | 是 | 协议版本，固定为 `"v1"` |
|
||||
|
||||
---
|
||||
|
||||
#### 2. Session Start: `session.start`
|
||||
|
||||
握手成功后发送的第二个消息，用于启动对话会话。
|
||||
客户端连接后发送的第一个消息，用于启动对话会话。
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -75,13 +57,17 @@ Server <- session.stopped
|
||||
"channels": 1
|
||||
},
|
||||
"metadata": {
|
||||
"appId": "assistant_123",
|
||||
"channel": "web",
|
||||
"configVersionId": "cfg_20260217_01",
|
||||
"systemPrompt": "你是简洁助手",
|
||||
"greeting": "你好，我能帮你什么？",
|
||||
"output": {
|
||||
"mode": "audio"
|
||||
"source": "web_debug",
|
||||
"history": {
|
||||
"userId": 1
|
||||
},
|
||||
"overrides": {
|
||||
"systemPrompt": "你是简洁助手",
|
||||
"greeting": "你好，我能帮你什么？",
|
||||
"output": {
|
||||
"mode": "audio"
|
||||
}
|
||||
},
|
||||
"dynamicVariables": {
|
||||
"customer_name": "Alice",
|
||||
@@ -101,17 +87,33 @@ Server <- session.stopped
|
||||
| `metadata` | object | 否 | 运行时配置 |
|
||||
|
||||
**metadata 支持的字段**：
|
||||
- `appId` / `app_id` - 应用 ID
|
||||
- `channel` - 渠道标识
|
||||
- `configVersionId` / `config_version_id` - 配置版本
|
||||
- `systemPrompt` - 系统提示词
|
||||
- `greeting` - 开场白
|
||||
- `output.mode` - 输出模式 (`audio` / `text`)
|
||||
- `source` - 来源标识
|
||||
- `history.userId` - 历史记录用户 ID
|
||||
- `overrides` - 可覆盖字段（仅限安全白名单）
|
||||
- `dynamicVariables` - 动态变量（支持 `{{variable}}` 占位符）
|
||||
|
||||
**`metadata.overrides` 白名单字段**：
|
||||
- `systemPrompt`
|
||||
- `greeting`
|
||||
- `firstTurnMode`
|
||||
- `generatedOpenerEnabled`
|
||||
- `output`
|
||||
- `bargeIn`
|
||||
- `knowledgeBaseId`
|
||||
- `knowledge`
|
||||
- `tools`
|
||||
- `openerAudio`
|
||||
|
||||
**限制**：
|
||||
- `metadata.workflow` 会被忽略（不触发 workflow 事件）
|
||||
- 禁止提交 `metadata.services`
|
||||
- 禁止提交 `assistantId` / `appId` / `app_id` / `configVersionId` / `config_version_id`
|
||||
- 禁止提交包含密钥语义的字段（如 `apiKey` / `token` / `secret` / `password` / `authorization`）
|
||||
|
||||
---
|
||||
|
||||
#### 3. Text Input: `input.text`
|
||||
#### 2. Text Input: `input.text`
|
||||
|
||||
发送文本输入，跳过 ASR 识别，直接触发 LLM 回复。
|
||||
|
||||
@@ -129,7 +131,7 @@ Server <- session.stopped
|
||||
|
||||
---
|
||||
|
||||
#### 4. Response Cancel: `response.cancel`
|
||||
#### 3. Response Cancel: `response.cancel`
|
||||
|
||||
请求中断当前回答。
|
||||
|
||||
@@ -147,7 +149,7 @@ Server <- session.stopped
|
||||
|
||||
---
|
||||
|
||||
#### 5. Tool Call Results: `tool_call.results`
|
||||
#### 4. Tool Call Results: `tool_call.results`
|
||||
|
||||
回传客户端执行的工具结果。
|
||||
|
||||
@@ -176,7 +178,7 @@ Server <- session.stopped
|
||||
|
||||
---
|
||||
|
||||
#### 6. Session Stop: `session.stop`
|
||||
#### 5. Session Stop: `session.stop`
|
||||
|
||||
结束对话会话。
|
||||
|
||||
@@ -194,7 +196,7 @@ Server <- session.stopped
|
||||
|
||||
---
|
||||
|
||||
#### 7. Binary Audio
|
||||
#### 6. Binary Audio
|
||||
|
||||
在 `session.started` 之后可持续发送二进制 PCM 音频。
|
||||
|
||||
@@ -239,7 +241,6 @@ Server <- session.stopped
|
||||
|
||||
| 事件 | 说明 |
|
||||
|---|---|
|
||||
| `hello.ack` | 握手成功响应 |
|
||||
| `session.started` | 会话启动成功 |
|
||||
| `config.resolved` | 服务端最终配置快照 |
|
||||
| `heartbeat` | 保活心跳（默认 50 秒间隔） |
|
||||
@@ -281,7 +282,10 @@ Server <- session.stopped
|
||||
| `protocol.invalid_json` | JSON 格式错误 |
|
||||
| `protocol.invalid_message` | 消息格式错误 |
|
||||
| `protocol.order` | 消息顺序错误 |
|
||||
| `protocol.version_unsupported` | 协议版本不支持 |
|
||||
| `protocol.assistant_id_required` | 缺少 `assistant_id` query 参数 |
|
||||
| `protocol.invalid_override` | metadata 覆盖字段不合法 |
|
||||
| `assistant.not_found` | assistant 不存在 |
|
||||
| `assistant.config_unavailable` | assistant 配置不可用 |
|
||||
| `audio.invalid_pcm` | PCM 数据无效 |
|
||||
| `audio.frame_size_mismatch` | 音频帧大小不匹配 |
|
||||
| `server.internal` | 服务端内部错误 |
|
||||
|
||||
Reference in New Issue
Block a user