> 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": { ... }
}
```

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

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

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

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

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

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

| 形态      | 事件类型所在位置     | 由……使用                                                                   |
| ------- | ------------ | ----------------------------------------------------------------------- |
| 服务器消息封装 | `data.type`  | 大多数消息                                                                   |
| 机器人输出流  | 顶层 `类型`      | `bot-llm-started`, `bot-llm-text`, `bot-llm-stopped`, `bot-tts-started` |
| 直接（旧版）  | 顶层 `类型`，字段扁平 | `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` | string | 触发此响应的原始客户端消息类型                                      |
| `状态`         | string | 处理状态： `"成功"`, `"error"`, `"processing"`, `"pending"` |
| `消息`         | string | 结果的人类可读描述（可选）                                        |
| `extras`     | 对象     | 附加的特定事件数据（可选）                                        |

**状态值：**

* `"成功"` - 消息已成功处理
* `"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-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-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-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-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-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#bot-turn-completed)                        |
| `机器人情绪`                         | 用于头像的机器人情绪          | 服务器消息封装 | [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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-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-to-client-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/server-to-client-messages.md#diagnostics)                               |
| `audio-data`                    | 通过数据通道传输的音频块（自定义模式） | 服务器消息封装 | 参见 [通过数据通道传输的音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)                                                     |
| `turn-complete`                 | 群聊轮次已结束             | 服务器消息封装 | [group-chat-messages.md](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/group-chat-messages.md#turn-complete)                                         |

**格式键：**

* **服务器消息封装**：使用完整的 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` | `text`                                                     |
| `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` - 重置空闲超时

### 动画与视觉反馈

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

* `机器人情绪` - 用于头像表情的情绪数据
* `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 调试事件（仅调试模式）

***

## 相关文档

* [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md) - 建立实时会话
* [轮次生命周期与消息顺序](/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.