> 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 中使用的所有消息类型提供了全面参考。消息通过 WebRTC 数据通道在您的客户端应用与 Convai 服务器之间双向传输。

***

## 消息方向

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

***

## 消息格式

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

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

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

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

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

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

```json
{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "<message-type>",
    ...payload fields
  }
}
```

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

{% hint style="info" %}
在详细消息文档页面中，为了清晰起见，示例只展示内部 `data` 负载。
{% endhint %}

***

## 服务器响应消息

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

**响应示例：**

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "Context updated successfully (append mode)",
  "extras": {
    "token_count": 1523,
    "max_tokens": 50000,
    "remaining_tokens": 48477
  }
}
```

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

**状态值：**

* `"success"` - 消息已成功处理
* `"error"` - 发生错误（请参见 `message` 以了解详情）
* `"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)              |
| `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)            |

***

## 服务器 → 客户端消息

| 消息类型                            | 用途                   | 格式      | 详情页                                                                                                                                                   |
| ------------------------------- | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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)            |
| `bot-emotion`                   | 头像的机器人情绪             | 服务器消息封装 | [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)           |
| `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) |
| `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)               |
| `audio-data`                    | 通过数据通道传输的音频片段（自定义模式） | 服务器消息封装 | 参见 [通过数据通道传输的音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)                                         |

**格式键：**

* **服务器消息封装**：使用完整的 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`                                                     |

***

## 错误响应示例

### 无效 JSON

```json
{
  "type": "server-response",
  "event_type": "parse-error",
  "status": "error",
  "message": "Failed to parse message: invalid JSON or UTF-8 encoding"
}
```

### 缺少类型字段

```json
{
  "type": "server-response",
  "event_type": "validation-error",
  "status": "error",
  "message": "Message missing required 'type' field"
}
```

### 未知消息类型

```json
{
  "type": "server-response",
  "event_type": "unknown-message-type",
  "status": "error",
  "message": "Unknown message type: unknown-message-type",
  "extras": {
    "supported_types": ["trigger-message", "context-update", "tts-toggle", ...]
  }
}
```

***

## 消息类别

### 上下文与状态管理

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

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

### 音频控制

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

* `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` - 要执行的动作和动画

### 转录与文本

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

* `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) - 建立实时会话
* [客户端到服务器消息](/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:

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

The question should be specific, self-contained, and written in natural language.
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.