> 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/server-to-client-messages.md).

# 服务器到客户端的消息

Convai Live API 服务器在活动会话期间通过 WebRTC 数据通道发送这些消息。每种消息类型都表示一个不同事件——确认、机器人状态变化、动画数据或会话限制。请参见 [消息术语表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md) 以查看所有消息类型及其信封格式的摘要。

{% hint style="info" %}
除 `server-response` 外，所有服务器消息都使用在 [`interaction-created`](#interaction-created)下所示的 RTVI 信封格式。本页后续示例仅展示内部的 `数据` 载荷，以便更清晰。
{% endhint %}

***

### 确认

#### server-response

`server-response` 会在每条客户端到服务器消息后发送，用于确认收到并报告处理结果。它使用 **直接（旧版）格式** ——不是 RTVI 信封——，因此字段会出现在 JSON 对象的顶层，而不是嵌套在 `数据`.

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "success",
  "message": "TTS 已启用",
  "extras": {
    "enabled": true
  }
}
```

| 字段        | 类型        | 说明                                                         |
| --------- | --------- | ---------------------------------------------------------- |
| `类型`      | string    | 始终 `"server-response"`                                     |
| `事件类型`    | string    | 触发此响应的客户端消息类型                                              |
| `状态`      | string    | 处理状态： `"success"`, `"error"`, `"processing"`，或 `"pending"` |
| `message` | 字符串 \| 空值 | 结果的人类可读描述                                                  |
| `附加信息`    | 对象 \| 空值  | 其他特定于事件的数据                                                 |

**状态值**

| 值              | 含义                     |
| -------------- | ---------------------- |
| `"success"`    | 消息处理成功                 |
| `"error"`      | 发生错误；请参见 `message` ，详见 |
| `"processing"` | 消息正在异步处理中              |
| `"pending"`    | 消息已收到，但处理延迟            |

**`附加信息` 按事件类型划分的字段**

| `事件类型`              | `附加信息` 字段                                                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `上下文更新`             | `token_count`, `static_token_count`, `runtime_token_count`, `max_tokens`, `static_max_tokens`, `runtime_max_tokens`, `remaining_tokens`, `内容` |
| `tts-toggle`        | `已启用`                                                                                                                                         |
| `stt-toggle`        | `muted`                                                                                                                                       |
| `触发消息`              | `trigger_name`, `has_speak_tag`                                                                                                               |
| `user_text_message` | `text`                                                                                                                                        |

**错误示例**

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "error",
  "message": "TTS 绕过过滤器不可用"
}
```

**验证错误 — 无效的 JSON**

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

**验证错误 — 缺少 type 字段**

```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"]
  }
}
```

**建议操作：** 请查看 `状态` 字段出现在每个 `server-response`响应中。处理 `"error"` 响应时，读取 `message` 并更新你的 UI。使用 `附加信息` 字段来反映当前状态——例如，在 `事件类型` 为 `stt-toggle`.

***

### 会话与生命周期

#### interaction-created

在会话生命周期早期发送，此时已创建 interaction ID。这是第一条携带完整 RTVI 信封的消息。

**完整的 RTVI 信封**

```json
{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "interaction-created",
    "interaction_id": "int_abc123def456",
    "character_session_id": "cs_xyz789"
  }
}
```

**内部 `数据` 载荷**

```json
{
  "type": "interaction-created",
  "interaction_id": "int_abc123def456",
  "character_session_id": "cs_xyz789"
}
```

| 字段                     | 类型     | 说明                         |
| ---------------------- | ------ | -------------------------- |
| `类型`                   | string | 始终 `"interaction-created"` |
| `interaction_id`       | string | 此交互会话的唯一标识符                |
| `character_session_id` | string | 角色会话标识符                    |

**建议操作：** 存储 `interaction_id` 用于分析、日志记录或会话跟踪。

***

#### usage-limit-reached

当使用配额超出时发送。处理此消息以显示适当反馈并关闭会话。

```json
{
  "type": "usage-limit-reached",
  "quota_type": "minutes",
  "message": "你已超出每月配额"
}
```

| 字段           | 类型     | 说明                                     |
| ------------ | ------ | -------------------------------------- |
| `类型`         | string | 始终 `"usage-limit-reached"`             |
| `quota_type` | string | 超出的配额类型，例如 `"minutes"` 或 `"api_calls"` |
| `message`    | string | 说明该限制的人类可读消息                           |

**建议操作：** 向用户显示 `message` 并优雅地结束会话。

***

#### bot-turn-completed

当机器人到达终止轮次状态时发送：它已说完、被用户打断，或因无法提供所需输出而中止。

```json
{
  "type": "bot-turn-completed",
  "was_interrupted": false
}
```

| 字段                | 类型     | 说明                                        |
| ----------------- | ------ | ----------------------------------------- |
| `类型`              | string | 始终 `"bot-turn-completed"`                 |
| `was_interrupted` | 布尔值    | `true` 如果用户打断了机器人； `false` 如果轮次正常完成       |
| `was_aborted`     | 布尔值    | 可选。 `true` 如果轮次因无法交付所需的机器人输出而结束           |
| `error_reason`    | string | 可选。机器可读的中止原因；目前 `"audio_delivery_failed"` |

`was_aborted` 是位于 `error_reason` 为附加的可选字段。正常完成时会省略它们。

**建议操作：** 收到此消息后，更新 UI 状态并重新启用用户输入控件。

***

#### user-idle-warning

当用户在配置的时间内处于空闲状态时发送，提醒即将断开连接。

```json
{
  "type": "user-idle-warning",
  "remaining_seconds": 300,
  "message": "你已空闲。你将在 5 分钟后断开连接。"
}
```

| 字段                  | 类型        | 说明                       |
| ------------------- | --------- | ------------------------ |
| `类型`                | string    | 始终 `"user-idle-warning"` |
| `remaining_seconds` | 整数        | 会话断开前剩余的秒数               |
| `message`           | 字符串 \| 空值 | 可选的人类可读警告消息              |

**建议操作：** 向用户显示警告并提示其活动，或者发送 [`reset-idle-timer`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/client-to-server-messages.md#reset-idle-timer) 消息以重置空闲计时器。

***

#### llm-no-response

当 LLM 明确决定不响应用户输入时发送。

```json
{
  "type": "llm-no-response",
  "reason": "abstain"
}
```

| 字段   | 类型        | 说明                            |
| ---- | --------- | ----------------------------- |
| `类型` | string    | 始终 `"llm-no-response"`        |
| `原因` | 字符串 \| 空值 | 无响应的原因； `"abstain"` 表示模型选择不发言 |

**建议操作：** 更新你的 UI，以表明机器人选择不响应，或者根据你的 UX 要求静默处理该事件。

***

### 交互与转写

#### 最终用户转写

在当前轮次中，随用户所说内容的最终转写一起发送。

```json
{
  "type": "final-user-transcription",
  "text": "Hello, how are you today?",
  "speaker_id": "user_123",
  "speaker_name": "Alice",
  "participant_id": "participant_456"
}
```

| 字段               | 类型        | 说明                              |
| ---------------- | --------- | ------------------------------- |
| `类型`             | string    | 始终 `"final-user-transcription"` |
| `text`           | string    | 转写文本                            |
| `speaker_id`     | 字符串 \| 空值 | 说话者标识符                          |
| `speaker_name`   | 字符串 \| 空值 | 说话者显示名称                         |
| `participant_id` | 字符串 \| 空值 | 参与者标识符                          |

**建议操作：** 显示 `text` 在聊天 UI 中显示，或将其追加到对话历史中。

***

#### moderation-response

当内容审核处理完用户输入时发送。

```json
{
  "type": "moderation-response",
  "result": false,
  "user_input": "被标记的内容",
  "reason": "不恰当的语言"
}
```

| 字段           | 类型        | 说明                              |
| ------------ | --------- | ------------------------------- |
| `类型`         | string    | 始终 `"moderation-response"`      |
| `结果`         | 布尔值       | `true` 如果内容通过了审核； `false` 如果被阻止 |
| `user_input` | string    | 已审核的输入文本                        |
| `原因`         | 字符串 \| 空值 | 阻止原因； `null` 如果内容通过了审核          |

**建议操作：** 如果 `结果` 为 `false`，可选择向用户显示反馈，说明输入已被阻止。

***

#### behavior-tree-response

随角色 AI 行为的行为树数据一起发送。

```json
{
  "type": "behavior-tree-response",
  "bt_code": "...",
  "bt_constants": "...",
  "narrative_section_id": "section_1"
}
```

| 字段                     | 类型     | 说明                            |
| ---------------------- | ------ | ----------------------------- |
| `类型`                   | string | 始终 `"behavior-tree-response"` |
| `bt_code`              | string | 行为树代码                         |
| `bt_constants`         | string | 行为树的常量                        |
| `narrative_section_id` | string | 当前叙事部分标识符                     |

***

### 动作

#### action-response

随机器人希望执行的动作或动画的有序列表一起发送。动作仅引用在 `action_config` 连接时 [Connect API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md) 中的详情。 `action_config`.

```json
{
  "type": "action-response",
  "actions": [
    { "name": "Move To", "target": "cube" },
    { "name": "Wave" }
  ]
}
```

| 字段                 | 类型     | 说明                     |
| ------------------ | ------ | ---------------------- |
| `类型`               | string | 始终 `"action-response"` |
| `actions`          | 对象\[]  | 要触发的有序动作数组             |
| `actions[].name`   | string | 动作或动画标识符               |
| `actions[].target` | string | 可选目标对象或角色名称            |

**建议操作：** 按顺序遍历 `actions` 并在你的头像或场景中触发相应的动画或行为。

***

### 动画与口型同步

#### bot-emotion

当机器人表达情绪时发送。可用于触发头像动画或更新视觉反馈元素。

```json
{
  "type": "bot-emotion",
  "emotion": "happy",
  "scale": 2
}
```

| 字段        | 类型     | 说明                                               |
| --------- | ------ | ------------------------------------------------ |
| `类型`      | string | 始终 `"bot-emotion"`                               |
| `emotion` | string | 情绪名称，例如 `"快乐"`, `"sad"`, `“excited”`，或 `"angry"` |
| `scale`   | 整数     | 强度级别： `1` = 轻微， `2` = 中等， `3` = 强烈               |

**建议操作：** 为收到的 `emotion` 是位于 `scale`.

***

#### visemes

在机器人说话期间频繁发送，携带用于头像口型动画的唇同步数据。值表示每种口型形状的混合权重。

```json
{
  "type": "visemes",
  "visemes": {
    "sil": 0.0,
    "pp": 0.8,
    "ff": 0.0,
    "th": 0.0,
    "dd": 0.0,
    "kk": 0.0,
    "ch": 0.0,
    "ss": 0.0,
    "nn": 0.0,
    "rr": 0.0,
    "aa": 0.2,
    "e": 0.0,
    "ih": 0.0,
    "oh": 0.0,
    "ou": 0.0
  }
}
```

| 字段        | 类型     | 说明                        |
| --------- | ------ | ------------------------- |
| `类型`      | string | 始终 `"visemes"`            |
| `visemes` | 对象     | 口型素键到混合权重的映射（`0.0`–`1.0`) |

**口型素键**

| 键     | 音素      |
| ----- | ------- |
| `sil` | 静音      |
| `pp`  | P、B、M   |
| `ff`  | F、V     |
| `th`  | TH      |
| `dd`  | T、D     |
| `kk`  | K、G     |
| `ch`  | CH、J、SH |
| `ss`  | S、Z     |
| `nn`  | N、L     |
| `rr`  | R       |
| `aa`  | A       |
| `e`   | E       |
| `ih`  | I       |
| `oh`  | O       |
| `ou`  | U、W     |

**建议操作：** 每次收到此消息时，都将 viseme 权重应用到头像口型同步的混合形状上。

***

#### neurosync-blendshapes

随单帧面部动画混合形状数据发送（每帧 251 个值）。

```json
{
  "type": "neurosync-blendshapes",
  "blendshapes": [0.0, 0.1, 0.05, 0.0]
}
```

| 字段            | 类型       | 说明                                |
| ------------- | -------- | --------------------------------- |
| `类型`          | string   | 始终 `"neurosync-blendshapes"`      |
| `blendshapes` | float\[] | 251 个混合形状值的数组，每个值的范围为 `0.0`–`1.0` |

**建议操作：** 将混合形状值应用到当前帧的头像面部骨骼绑定。

***

#### chunked-neurosync-blendshapes

随多个帧的混合形状数据批量打包成单条消息发送。当服务器为了效率发送批量数据时，请使用此消息类型，而不要使用 `neurosync-blendshapes` 当服务器为了效率发送批量数据时。

```json
{
  "type": "chunked-neurosync-blendshapes",
  "blendshapes": [
    [0.0, 0.1, 0.05],
    [0.02, 0.12, 0.04],
    [0.01, 0.09, 0.06]
  ]
}
```

| 字段            | 类型          | 说明                                   |
| ------------- | ----------- | ------------------------------------ |
| `类型`          | string      | 始终 `"chunked-neurosync-blendshapes"` |
| `blendshapes` | float\[]\[] | 混合形状帧数组；每一帧包含 251 个值，范围为 `0.0`–`1.0` |

**建议操作：** 将这些帧排队并按顺序应用，以生成平滑的面部动画。

***

#### blendshape-turn-stats

在机器人轮次结束时发送，包含该轮次混合形状生成的统计信息。可用于调试或分析。

```json
{
  "type": "blendshape-turn-stats",
  "stats": {
    "total_blendshapes": 150,
    "total_audio_bytes": 48000,
    "total_turn_duration_ms": 3000.0,
    "total_audio_duration_ms": 2800.0,
    "fps": 50.0,
    "was_interrupted": false
  }
}
```

| 字段                              | 类型     | 说明                           |
| ------------------------------- | ------ | ---------------------------- |
| `类型`                            | string | 始终 `"blendshape-turn-stats"` |
| `stats.total_blendshapes`       | 整数     | 本轮生成的 blendshape 帧总数         |
| `stats.total_audio_bytes`       | 整数     | 音频数据总大小（字节）                  |
| `stats.total_turn_duration_ms`  | float  | 本轮总时长（毫秒）                    |
| `stats.total_audio_duration_ms` | float  | 音频总时长（毫秒）                    |
| `stats.fps`                     | float  | blendshape 帧每秒数              |
| `stats.was_interrupted`         | 布尔值    | `true` 如果本轮在完成前被中断           |

***

### 音频

#### 音频数据

当音频通过数据通道而不是（或除了）标准 WebRTC 音频轨道路由时发送。仅在以下情况下才会收到此消息： `音频路由` 被设置为 `"data_only"` 或 `"both"` 在 `音频配置` 的 `/connect` 请求。

```json
{
  "type": "audio-data",
  "sample_rate": 48000,
  "channels": 1,
  "audio": "AAEAAg==...",
  "includes_wav_header": false
}
```

| 字段          | 类型     | 说明                                              |
| ----------- | ------ | ----------------------------------------------- |
| `类型`        | string | 始终 `"audio-data"`                               |
| `采样率`       | 整数     | 音频采样率（Hz），例如 `16000`, `24000`，或 `48000`         |
| `声道数`       | 整数     | 音频声道数： `1` = 单声道， `2` = 立体声                     |
| `音频`        | string | Base64 编码的音频数据（原始 PCM 或带头部的 WAV）                |
| `包含 WAV 头部` | 布尔值    | `true` 如果音频负载包含 44 字节的 WAV 头部； `false` 对于原始 PCM |

有关完整的解码步骤、播放实现和配置选项，请参阅 [通过数据通道传输音频数据](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md).

***

### 相关页面

{% content-ref url="/pages/52997086a1139479d2cbe158e37133880276b547" %}
[消息术语表](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md)
{% endcontent-ref %}

{% content-ref url="/pages/70d752d330612b0fbf1290588e718236d6a18f0e" %}
[Connect API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/29ba5f52bd1ff6aac10fb390cafb074f474ab066" %}
[音频数据（通过数据通道）](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/audio-data-via-data-channel.md)
{% endcontent-ref %}


---

# 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/server-to-client-messages.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.