> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md).

# 消息术语表

Convai Live API 中用于客户端与服务器之间实时通信的所有消息类型的完整术语表。

此术语表总结了 Convai 的实时 API 中使用的消息类型。消息通过 WebRTC 数据通道在你的客户端应用与 Convai 之间双向流动。

***

## 消息方向

| 方向            | 描述                       |
| ------------- | ------------------------ |
| **客户端 → 服务器** | 你发送的消息，用于触发操作、更新状态或控制机器人 |
| **服务器 → 客户端** | 你接收的消息，用于事件、状态变化和实时数据    |

***

## 消息格式

### 客户端 → 服务器消息

从客户端发送到服务器的消息使用以下结构：

```json
{
  "type": "<message-type>",
  "data": { ... }
}
```

* `type` *（字符串，必需）*：消息类型标识符
* `data` *（对象，可选）*：消息载荷（结构因类型而异）

### 服务器 → 客户端消息

服务器发送给客户端的大多数消息都封装在 RTVI 信封中：

```json
{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "<message-type>",
    ...载荷字段
  }
}
```

* `label` *（字符串）*：始终为 `"rtvi-ai"`
* `type` *（字符串）*：始终为 `"server-message"` 用于自定义服务器消息
* `data` *（对象）*：包含实际消息及其自身的 `type` 以及载荷字段

总共有 **三种信封结构** ，客户端必须全部处理：

| 结构                  | 事件类型所在位置       | 适用于                                                                     |
| ------------------- | -------------- | ----------------------------------------------------------------------- |
| 经 server-message 封装 | `data.type`    | 大多数消息                                                                   |
| 机器人输出流              | 顶层 `type`      | `bot-llm-started`, `bot-llm-text`, `bot-llm-stopped`, `bot-tts-started` |
| 直接（旧版）              | 顶层 `type`，字段扁平 | `server-response`                                                       |

如下确定实际事件类型：

```javascript
function eventType(message) {
  return message.type === "server-message" && message.data?.type
    ? message.data.type
    : message.type;
}
```

{% hint style="info" %}
在详细消息文档页面中，示例只显示内部的 `data` 载荷，以便更清晰。
{% endhint %}

### 字段存在性

是 **不统一** 在不同消息类型之间。有些可选字段会以 `null`；其他字段则完全从 JSON 中省略；嵌套的可选字段，例如 `action-response.actions[].target` 在未设置时会被丢弃。

编写客户端时要有防御性——使用可选访问，而不是空值检查。完整规则见 [字段存在性规则](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md#field-presence-rules).

***

## 服务器响应消息

对于每一条客户端到服务器的消息，服务器都会自动发送一条 `server-response` 消息，用于确认接收并指示处理状态。这类似于 REST API 中的 HTTP 响应码。

**响应示例：**

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "上下文更新成功（追加模式）",
  "extras": {
    "token_count": 1523,
    "max_tokens": 50000,
    "remaining_tokens": 48477
  }
}
```

| 字段           | 输入  | 描述                                                        |
| ------------ | --- | --------------------------------------------------------- |
| `event_type` | 字符串 | 触发此响应的原始客户端消息类型                                           |
| `status`     | 字符串 | 处理状态： `"success"`, `"error"`, `"processing"`, `"pending"` |
| `消息`         | 字符串 | 结果的人类可读描述（可选）                                             |
| `extras`     | 对象  | 附加的特定于事件的数据（可选）                                           |

**状态值：**

* `"success"` - 消息已成功处理
* `"error"` - 发生错误（详见 `消息` ）
* `"processing"` - 消息正在异步处理
* `"pending"` - 消息已收到，但处理延迟

***

## 客户端 → 服务器消息

| 消息类型                          | 目的                      | 详情页                                                                                                                                                 |
| ----------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trigger-message`             | 触发叙事事件或发送上下文            | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#trigger-message)             |
| `user_text_message`           | 将文本输入作为用户发送             | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#user_text_message)           |
| `update-template-keys`        | 更新提示模板变量                | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#update-template-keys)        |
| `update-scene-metadata`       | 更新场景对象                  | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#update-scene-metadata)       |
| `update-dynamic-info`         | 更新动态上下文（基础）             | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#update-dynamic-info)         |
| `context-update`              | 更新运行时上下文（带模式控制）         | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#context-update)              |
| `action-result`               | 返回一个关联的 v2 客户端工具结果      | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#action-result)               |
| `vision-status`               | 查询视觉缓冲区状态               | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-status)               |
| `vision-trigger`              | 附加缓冲帧 / 触发视觉            | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#vision-trigger)              |
| `tts-toggle`                  | 启用/禁用机器人音频              | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#tts-toggle)                  |
| `stt-toggle`                  | 静音/取消静音语音识别             | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#stt-toggle)                  |
| `interrupt-bot`               | 立即停止机器人语音               | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#interrupt-bot)               |
| `force-user-stopped-speaking` | 指示用户语音结束（按住说话）          | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#force-user-stopped-speaking) |
| `reset-idle-timer`            | 重置空闲超时监控                | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#reset-idle-timer)            |
| `usage-toggle`                | 启用/禁用客户端使用量流            | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#usage-toggle)                |
| `kill-pipeline`               | 结束会话                    | [client-to-server-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#kill-pipeline)               |
| `group-address`               | 为一次轮次指定群聊房间             | [group-chat-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/group-chat-messages.md#group-address)                           |
| `group-address-part`          | 大型消息的一帧 `group-address` | [group-chat-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/group-chat-messages.md#group-address-part)                      |

***

## 服务器 → 客户端消息

| 消息类型                            | 目的                  | 格式                  | 详情页                                                                                                                                                               |
| ------------------------------- | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bot-llm-started`               | 模型生成开始              | 机器人输出流              | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-llm-started-bot-llm-stopped)           |
| `bot-llm-text`                  | 所选的旧版或原始文本投影        | 机器人输出流              | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-llm-text)                              |
| `bot-llm-stopped`               | 模型生成结束              | 机器人输出流              | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-llm-started-bot-llm-stopped)           |
| `bot-tts-started`               | 语音合成开始              | 机器人输出流              | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-tts-started)                           |
| `bot-started-speaking`          | 机器人音频开始             | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-started-speaking-bot-stopped-speaking) |
| `bot-stopped-speaking`          | 机器人音频结束             | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-started-speaking-bot-stopped-speaking) |
| `server-response`               | 每条客户端消息的响应          | 直接（旧版）              | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#server-response)                           |
| `interaction-created`           | 创建交互 ID             | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#interaction-created)                       |
| `usage-limit-reached`           | 配额超出通知              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#usage-limit-reached)                       |
| `bot-turn-completed`            | 机器人完成发言             | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-turn-completed)                        |
| `bot-emotion`                   | 用于头像的机器人情绪          | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-emotion)                               |
| `behavior-tree-response`        | 行为树数据               | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#behavior-tree-response)                    |
| `moderation-response`           | 内容审核结果              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#moderation-response)                       |
| `model-output`                  | 规范化的类型化 v2 模型输出     | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#model-output)                              |
| `action-response`               | 要触发的动作/动画           | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#action-response)                           |
| `final-user-transcription`      | 用户语音转写              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#final-user-transcription)                  |
| `visemes`                       | 口型同步数据              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#visemes)                                   |
| `neurosync-blendshapes`         | 面部动画数据              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#neurosync-blendshapes)                     |
| `chunked-neurosync-blendshapes` | 批量面部动画              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#chunked-neurosync-blendshapes)             |
| `neurosync-blendshapes-cancel`  | 丢弃缓冲的预先传递视觉内容       | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#neurosync-blendshapes-cancel)              |
| `blendshape-turn-stats`         | 轮次统计                | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#blendshape-turn-stats)                     |
| `user-idle-warning`             | 空闲超时警告              | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#user-idle-warning)                         |
| `llm-no-response`               | LLM 选择不响应           | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#llm-no-response)                           |
| `vad-stt-started`               | STT 开始转写            | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#vad-stt-started)                           |
| `vad-stt-stopped`               | STT 停止转写            | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#vad-stt-stopped)                           |
| `vad-stt-debug`                 | VAD 调试事件（仅调试会话）     | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#vad-stt-debug)                             |
| `turn-trace`                    | 每轮时序跟踪（仅调试会话）       | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#diagnostics)                               |
| `server-log`                    | 服务器日志行（仅调试会话）       | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#diagnostics)                               |
| `usage-update`                  | 每轮使用量和成本（仅调试会话）     | 经 server-message 封装 | [server-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#diagnostics)                               |
| `audio-data`                    | 通过数据通道传输的音频块（自定义模式） | 经 server-message 封装 | 参见 [通过数据通道传输的音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)                                                     |
| `turn-complete`                 | 群聊轮次结束              | 经 server-message 封装 | [group-chat-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/group-chat-messages.md#turn-complete)                                         |

**格式键：**

* **经 server-message 封装**：使用完整的 RTVI 信封格式，包含 `"type": "server-message"` 以及嵌套在其中的事件数据 `data.type` 以及后续字段
* **直接（旧版）**：使用 `data` 作为一个扁平对象，事件类型和字段位于顶层

{% hint style="info" %}
所有客户端消息都会收到一条 `server-response` 带有成功/错误状态和附加数据的确认响应。
{% endhint %}

***

## 按事件类型划分的通用响应附加字段

当你收到一条 `server-response` 消息时， `extras` 字段可能包含特定于事件的数据：

| 事件类型                | 附加字段                                                       |
| ------------------- | ---------------------------------------------------------- |
| `context-update`    | `token_count`, `max_tokens`, `remaining_tokens`, `content` |
| `tts-toggle`        | `enabled`                                                  |
| `stt-toggle`        | `muted`                                                    |
| `trigger-message`   | `trigger_name`, `has_speak_tag`                            |
| `user_text_message` | `文本`                                                       |
| `action-result`     | `tool_call_id`, `idempotent`；错误还包括 `error_code`            |

***

## 错误响应示例

### 无效 JSON

```json
{
  "type": "server-response",
  "event_type": "parse-error",
  "status": "error",
  "message": "解析消息失败：JSON 无效或 UTF-8 编码错误"
}
```

### 缺少类型字段

```json
{
  "type": "server-response",
  "event_type": "validation-error",
  "status": "error",
  "message": "消息缺少必需的 'type' 字段"
}
```

### 未知消息类型

```json
{
  "type": "server-response",
  "event_type": "unknown-message-type",
  "status": "error",
  "message": "未知的消息类型：unknown-message-type",
  "extras": {
    "supported_types": ["trigger-message", "context-update", "tts-toggle", ...]
  }
}
```

***

## 消息类别

### 机器人响应

角色自身的输出：

* `bot-llm-started` / `bot-llm-stopped` - 模型生成边界
* `bot-llm-text` - 所选的旧版或原始文本投影
* `model-output` - 经过协商 model output v2 的客户端所使用的规范化类型化输出
* `bot-tts-started` - 语音合成开始
* `bot-started-speaking` / `bot-stopped-speaking` - 音频边界
* `bot-turn-completed` - 轮次的服务器端终止状态

### 上下文与状态管理

用于管理对话上下文和机器人状态的消息：

* `context-update` - 带模式控制的统一上下文更新，包括动作可供性
* `update-dynamic-info` - 基础动态上下文更新
* `update-template-keys` - 更新提示模板变量
* `update-scene-metadata` - 更新场景对象描述

### 代理式动作

用于相关联的客户端执行工具的消息：

* `action-response` - 旧版语义动作或 v2 工具调用兼容性投影
* `model-output` - 选择 model output v2 时的规范化语义项
* `action-result` - v2 的终端客户端结果 `tool_call`

### 视觉

用于查询和消费视觉缓冲区的消息：

* `vision-status` - 查询是否有可用帧并检查缓冲区状态
* `vision-trigger` - 附加缓冲帧，并可选择触发机器人轮次

### 音频控制

用于控制音频输入和输出的消息：

* `tts-toggle` - 启用/禁用文本转语音输出
* `stt-toggle` - 静音/取消静音语音转文本输入
* `interrupt-bot` - 中断当前机器人语音
* `force-user-stopped-speaking` - 指示用户语音结束

### 交互与事件

用于触发事件和发送用户输入的消息：

* `trigger-message` - 触发叙事事件或上下文动作
* `user_text_message` - 发送文本作为用户输入

### 会话管理

用于管理会话生命周期的消息：

* `reset-idle-timer` - 重置空闲超时

### 动画与视觉反馈

包含动画和视觉数据的消息：

* `bot-emotion` - 用于头像表情的情绪数据
* `visemes` - 口型同步 blendshape 数据
* `neurosync-blendshapes` - 面部动画 blendshape（单帧）
* `chunked-neurosync-blendshapes` - 批量面部动画 blendshape
* `action-response` - 语义动作或 v2 客户端工具调用投影

### 转写与文本

包含文本和转写数据的消息：

* `final-user-transcription` - 用户语音的最终转写

### 系统事件

关于系统状态和事件的消息：

* `server-response` - 客户端消息的确认
* `interaction-created` - 创建会话交互 ID
* `bot-turn-completed` - 机器人轮次结束
* `usage-limit-reached` - 使用配额超出
* `user-idle-warning` - 用户空闲超时警告
* `llm-no-response` - LLM 选择不响应

### 语音活动检测

来自基于 VAD 的 STT 门控系统的消息：

* `vad-stt-started` - STT 服务开始转写
* `vad-stt-stopped` - STT 服务停止转写
* `vad-stt-debug` - VAD 调试事件（仅调试模式）

***

## 相关文档

* [Connect API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md) - 建立实时会话
* [Turn 生命周期和消息顺序](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/turn-lifecycle-and-message-ordering.md) - 一个轮次如何传递，以及你可以依赖的顺序
* [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md) - 语音、动作和情绪如何分离，以及服务器会移除什么
* [客户端到服务器消息](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md) - 详细的客户端消息参考
* [服务器到客户端消息](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md) - 详细的服务器消息参考
* [通过数据通道传输的音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md) - 自定义音频处理
* [指标](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/metrics.md) - 性能指标和监控

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.