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

# 客户端到服务器消息

参考客户端通过 WebRTC 数据通道发送到 Convai Live API 服务器的所有消息，包括载荷、字段和响应细节。

所有客户端到服务器的消息均以 JSON 格式通过 WebRTC 数据通道发送。该通道在成功完成 `/connect` 调用后建立。有关消息格式约定、服务器返回的状态码，以及双向所有消息类型的完整索引，请参阅 [消息术语表](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/message-glossary.md).

### 消息封装

每条客户端到服务器的消息都使用以下封装格式：

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

| 字段     | 类型  | 必填 | 说明                               |
| ------ | --- | -- | -------------------------------- |
| `type` | 字符串 | 是  | 消息类型标识符。                         |
| `data` | 对象  | 否  | 消息负载。结构因消息类型而异。对于没有负载的消息，请省略此字段。 |

服务器会通过一条 `server-response` 消息确认每条客户端消息。请参阅下文的 [服务器响应](#server-response) 。

### 服务器响应

服务器会针对收到的每条客户端到服务器消息（无论其类型如何）发送一条 `server-response` 消息。

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

| 字段           | 类型        | 说明                                                         |
| ------------ | --------- | ---------------------------------------------------------- |
| `event_type` | 字符串       | 触发此响应的客户端消息类型。                                             |
| `status`     | 字符串       | 处理状态： `"success"`, `"error"`, `"processing"`或 `"pending"`. |
| `message`    | 字符串或 null | 对处理结果的人类可读描述。                                              |
| `extras`     | 对象或 null  | 事件专属的附加数据。结构因事件类型而异。                                       |

**状态值：**

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

***

### 交互与事件

#### trigger-message

触发叙事事件、向机器人发送上下文信息，或启动特定的机器人行为。

```json
{
  "type": "trigger-message",
  "data": {
    "trigger_name": "greeting",
    "trigger_message": "User entered the room"
  }
}
```

| 字段                | 类型  | 必填 | 说明            |
| ----------------- | --- | -- | ------------- |
| `trigger_name`    | 字符串 | 否  | 触发器的名称或标识符。   |
| `trigger_message` | 字符串 | 否  | 触发器的上下文或消息内容。 |

**使用场景：**

* 将场景内事件通知机器人，例如玩家进入某个区域或完成任务。
* 发送上下文触发信息，推动叙事发展。
* 启动与命名触发器关联的特定机器人行为。

**服务器响应附加字段：**

| 字段              | 类型  | 说明                 |
| --------------- | --- | ------------------ |
| `trigger_name`  | 字符串 | 请求中的触发器名称回显。       |
| `has_speak_tag` | 布尔值 | 触发消息是否包含 speak 标签。 |

***

#### user\_text\_message

将文本作为用户输入发送，模拟语音，但不发送音频。

```json
{
  "type": "user_text_message",
  "data": {
    "text": "Hello, how are you?"
  }
}
```

| 字段     | 类型  | 必填 | 说明           |
| ------ | --- | -- | ------------ |
| `text` | 字符串 | 是  | 作为用户输入发送的文本。 |

**服务器响应附加字段：**

| 字段     | 类型  | 说明        |
| ------ | --- | --------- |
| `text` | 字符串 | 请求中的文本回显。 |

***

### 上下文与状态

#### update-template-keys

更新机器人系统提示中使用的模板变量。

```json
{
  "type": "update-template-keys",
  "data": {
    "template_keys": {
      "player_name": "Alice",
      "current_level": "5",
      "location": "Forest"
    }
  }
}
```

| 字段              | 类型 | 必填 | 说明                     |
| --------------- | -- | -- | ---------------------- |
| `template_keys` | 对象 | 是  | 模板变量名称及其更新后字符串值组成的键值对。 |

**使用场景：**

* 更新玩家名称、属性或游戏状态等动态提示变量。
* 根据当前会话状态自定义机器人回复。

***

#### update-scene-metadata

更新机器人已知的场景描述上下文，包括场景内的物体及其描述。

```json
{
  "type": "update-scene-metadata",
  "data": {
    "scene_metadata": [
      { "name": "torch", "description": "A flaming torch on the wall" },
      { "name": "door", "description": "A locked wooden door" },
      { "name": "chest", "description": "An old treasure chest" }
    ]
  }
}
```

| 字段                                  | 类型        | 必填 | 说明          |
| ----------------------------------- | --------- | -- | ----------- |
| `data.scene_metadata`               | object\[] | 是  | 要描述的场景物体数组。 |
| `data.scene_metadata[].name`        | 字符串       | 是  | 物体标识符。      |
| `data.scene_metadata[].description` | 字符串       | 是  | 对象的人类可读描述。  |

**使用场景：**

* 随着环境变化，更新场景中的可交互对象。
* 调整机器人程序的环境上下文，但不修改动作可供性。

`update-scene-metadata` 仅更新描述性上下文，不会修改 `action_config.objects`。使用 [`context-update`](#context-update) 来替换语义动作对象；若要更改 v2 客户端的工具声明，则重新连接。

***

#### update-dynamic-info

更新注入机器人程序系统提示词中的动态信息。对于简单的单字段上下文更新，请使用此项。对于需要跟踪令牌预算的模式控制更新，请改用 [`context-update`](#context-update) 。

```json
{
  "type": "update-dynamic-info",
  "data": {
    "dynamic_info": {
      "text": "The user completed the dragon quest and received a golden sword."
    }
  }
}
```

| 字段                  | 类型  | 必填 | 说明                |
| ------------------- | --- | -- | ----------------- |
| `dynamic_info.text` | 字符串 | 是  | 要注入系统提示词的动态上下文文本。 |

***

#### context-update

更新机器人程序的运行时动态上下文，并全面控制模式、令牌预算以及是否触发 LLM。这是管理运行时上下文的首选消息。

```json
{
  "type": "context-update",
  "data": {
    "text": "New context information",
    "mode": "append",
    "run_llm": "auto",
    "current_attention_object": "torch",
    "action_config": {
      "objects": [
        { "name": "torch", "description": "A flaming torch on the wall" }
      ]
    },
    "remove_static": false
  }
}
```

| 字段                         | 类型     | 必填                      | 默认值        | 说明                                     |
| -------------------------- | ------ | ----------------------- | ---------- | -------------------------------------- |
| `text`                     | 字符串    | 是，除非 `mode` 为 `"reset"` | —          | 要应用的上下文文本。                             |
| `mode`                     | 字符串    | 否                       | `"append"` | 应用上下文的方式。                              |
| `run_llm`                  | 字符串    | 否                       | `"auto"`   | 更新后是否触发 LLM 响应。                        |
| `current_attention_object` | 字符串或对象 | 否                       | —          | 更新用于动作指代定位的当前关注对象。                     |
| `action_config`            | 对象     | 否                       | —          | 替换当前会话中提供的动作可供性列表。见下文。                 |
| `remove_static`            | 布尔值    | 否                       | `false`    | 仅适用于 `"reset"` 模式：当 `true`时，也会清除静态上下文。 |

**在会话中更新动作交互选项**

`action_config` 接受 Connect API 中的语义 `actions`, `objects`, `characters`和 `current_attention_object` 字段。 [Connect API](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md#request-body)。仅替换你提供的列表——只发送 `objects` 会保留 `actions` 和 `characters` 不变。当场景发生变化、角色的语义交互选项也随之变化时，请使用此功能。

`action_config.tools` 的作用范围是连接级别。包含 `context-update` 的请求若包含 `tools` 会返回错误；如需替换客户端工具声明，请重新连接。向 `scene_description` 或 `text` 中添加对象，并不会使其成为语义动作目标。请参阅 [响应约定与解析](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md).

**模式值**

| 值           | 行为                                                          |
| ----------- | ----------------------------------------------------------- |
| `"append"`  | 将 `text` 添加到现有的运行时动态上下文。                                    |
| `"replace"` | 使用 `text`.                                                  |
| `"reset"`   | 清除运行时动态上下文。如果 `remove_static` 为 `true`. `则也会清除静态上下文。` 无需提供。 |

**run\_llm 值**

| 值         | 行为                    |
| --------- | --------------------- |
| `"true"`  | 更新后始终触发机器人回复。         |
| `"false"` | 永不触发机器人回复。            |
| `"auto"`  | Convai 根据上下文决定是否触发回复。 |

**令牌预算**

动态上下文使用估算的令牌预算：

| 分区                                      | 预算                |
| --------------------------------------- | ----------------- |
| `static_text` （连接时提供的会话级上下文）            | 预计 20,000 个 token |
| 运行时 `text` （来自 `append` 和 `replace` 更新） | 预计 30,000 个 token |
| 动态上下文总量                                 | 预计 50,000 个 token |

当运行时 `text` 超过其 30,000-token 配额时，Convai 会删减最旧的运行时上下文更新，并保留配额范围内最新的更新。

`static_text` 是为此连接提供的会话和环境上下文。除非 `reset` 调用时 `remove_static` 为 `true`.

**注意对象更新规则**

* `current_attention_object` 会根据已连接会话的 `action_config.objects`.
* 发送对象名称字符串或完整对象载荷。
* 发送空字符串（`""`）以清除当前注意对象。
* 更新 `current_attention_object` 会重新生成系统提示，即使 `run_llm` 为 `"false"`.

**成功响应**

成功时，服务器会返回一个 `server-response` ，其中包含以下 `extras`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "Context updated successfully (append mode)",
  "extras": {
    "token_count": 1523,
    "static_token_count": 200,
    "runtime_token_count": 1323,
    "max_tokens": 50000,
    "static_max_tokens": 20000,
    "runtime_max_tokens": 30000,
    "remaining_tokens": 48477,
    "content": "full context text here..."
  }
}
```

| 字段                    | 类型  | 说明                             |
| --------------------- | --- | ------------------------------ |
| `token_count`         | 整数  | 动态上下文中当前估算的 token 总数。          |
| `static_token_count`  | 整数  | 静态动态上下文中的估算 token 数。           |
| `runtime_token_count` | 整数  | 运行时动态上下文中的估算 token 数。          |
| `max_tokens`          | 整数  | 动态上下文总预算（估算 50,000 个 token）。   |
| `static_max_tokens`   | 整数  | 静态动态上下文预算（估算 20,000 个 token）。  |
| `runtime_max_tokens`  | 整数  | 运行时动态上下文预算（估算 30,000 个 token）。 |
| `remaining_tokens`    | 整数  | 达到总限制前剩余的估算 token 数。           |
| `content`             | 字符串 | 保留的完整运行时动态上下文文本。               |

旧版 `word_count`, `static_word_count`, `runtime_word_count`, `max_words`，以及 `remaining_words` 字段可能会出现在较旧的客户端中。token 字段具有权威性。

**错误响应**

超出 token 限制时，服务器会返回一个 `server-response` 其中包含 `"status": "error"`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "error",
  "message": "Failed to process context-update: 1 validation error for DynamicInfo\nValue error, Dynamic info static_text token limit exceeded. static_text: 20001 estimated tokens, Maximum: 20000 tokens."
}
```

* 验证会分别检查静态、运行时和总估算 token 限制。
* 当动态上下文总量超过 40,000 个估算 token 时，Convai 会记录一条服务器端警告。
* 错误消息包含两个分区的估算 token 数明细。

***

### 智能体操作结果

#### action-result

为客户端执行的工具调用返回一个终结结果。此消息要求使用操作协议 v2，并与 `id` 中的 ID 关联，该 ID 位于 `tool_call` 项目中，或位于 v2 `action-response` 投影中。

```json
{
  "type": "action-result",
  "data": {
    "id": "call_abc123",
    "status": "completed",
    "output": {
      "record_opened": true
    },
    "character_session_id": "CHARACTER_SESSION_ID"
  }
}
```

| 字段                     | 类型     | 必填 | 说明                                              |
| ---------------------- | ------ | -- | ----------------------------------------------- |
| `id`                   | 字符串    | 是  | 来自工具调用的关联 ID。长度为 `1`–`256` 个字符。                 |
| `status`               | 字符串    | 是  | 终端状态： `"completed"`, `"error"`，或 `"cancelled"`. |
| `output`               | JSON 值 | 否  | 结果数据。模型需要操作的输出时，与 `"completed"` 配合使用。           |
| `error`                | JSON 值 | 否  | 失败或取消详情。已完成的结果不能包含此字段。                          |
| `character_session_id` | 字符串    | 否  | 会话保护字段。若存在，其值必须与当前角色会话匹配。                       |

Convai 不会执行或授权所请求的操作。请验证工具名称和参数，应用程序的权限和确认规则，在客户端执行操作，然后返回终端结果。

候选实现接受的最大序列化结果大小为 `64 KiB`。最多允许 `8` 个未完成调用，且每个用户轮次最多允许 `8` 轮工具结果续接。默认情况下，Convai 每次等待结果 `60` 秒。调用超时后会变为过期，迟到的结果将被拒绝。

接受结果后会返回以下确认信息：

```json
{
  "type": "server-response",
  "event_type": "action-result",
  "status": "success",
  "message": "Tool result accepted",
  "extras": {
    "tool_call_id": "call_abc123",
    "idempotent": false
  }
}
```

对同一 `id` 重试发送相同的终端负载会被接受，并返回 `extras.idempotent: true`。对已完成的 `id` 发送不同的终端负载会返回 `conflicting_terminal_tool_result`。对于未知、过期、跨会话、超大或参与者不匹配的结果，会返回带有 `server-response` 的错误消息，其中包含 `extras.error_code` 以及（若可用） `extras.tool_call_id`.

接受结果后，Convai 会将其提供给相同的模型上下文，以便继续生成。确认消息不构成顺序屏障；续接输出可能会先于其对应的 `server-response`到达。不同调用可能并行处于未完成状态。不要据此推断 SDK 或 Convai 会按顺序执行这些调用。

***

### 视觉

视觉消息会查询或使用会话的视觉环形缓冲区。设置 `vision_input_config` 于 [`/connect`](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)后，帧会从 WebRTC 视频轨道（LiveKit）进入该缓冲区。这些 RTVI 控制消息本身不会发布图像字节。

#### vision-status

查询当前视觉缓冲区状态，不附加帧，也不会触发 LLM。启用视觉功能后、关闭摄像头后，或在调用 `vision-trigger`.

```json
{
  "type": "vision-status",
  "data": {
    "update_id": "vision-status-1"
  }
}
```

| 字段          | 类型  | 必填 | 说明                                                         |
| ----------- | --- | -- | ---------------------------------------------------------- |
| `update_id` | 字符串 | 否  | 客户端关联 ID。会在确认消息中原样返回，并用于重复请求重放。如果未提供，则在顶层消息中 `id` 存在时会使用它。 |

**成功响应**

```json
{
  "type": "server-response",
  "event_type": "vision-status",
  "status": "success",
  "message": "Vision status",
  "extras": {
    "vision_status_outcome": "frames_available",
    "active_source": "participant-id",
    "active_source_label": "webcam",
    "last_frame_age_ms": 120,
    "update_id": "vision-status-1",
    "duplicate": false,
    "vision_buffer": {
      "enabled": true,
      "status": "frames_available",
      "retained_frames": 3,
      "buffer_frames": 8,
      "frames_per_turn": 5,
      "first_frame_pts": 1001,
      "last_frame_pts": 1003,
      "last_frame_age_ms": 120,
      "first_frame_index": -3,
      "source_active": true,
      "source_label": "webcam",
      "selected_participant": "participant-id",
      "sampling_windows": [
        { "count": 3, "interval_ms": 300 },
        { "count": 2, "interval_ms": 1500 }
      ]
    }
  }
}
```

| 字段                      | 类型              | 说明                                  |
| ----------------------- | --------------- | ----------------------------------- |
| `vision_status_outcome` | 字符串             | 缓冲区的总体结果。                           |
| `active_source`         | string \| null  | 当前有活动源时所选参与者的 ID。                   |
| `active_source_label`   | string \| null  | 已知时的人类可读源标签。                        |
| `last_frame_age_ms`     | integer \| null | 最新保留帧的时长（毫秒）。                       |
| `vision_buffer`         | 对象              | 客户端安全的环形缓冲区快照。绝不包含图像字节。             |
| `update_id`             | 字符串             | 如果请求中提供了该值，则会原样返回。                  |
| `duplicate`             | 布尔值             | `true` 当此确认消息是先前消息的重放时 `update_id`. |

**`vision_status_outcome` / `vision_buffer.status` 取值**

| 值                    | 含义                  |
| -------------------- | ------------------- |
| `frames_available`   | 来源处于活动状态，且缓冲区中保留了帧。 |
| `buffer_empty`       | 来源处于活动状态，但尚未保留任何帧。  |
| `no_active_video`    | 未选择活动视觉来源。          |
| `vision_not_enabled` | 此会话未启用视觉功能。         |

**使用场景：**

* 确认用户启用摄像头或屏幕共享后，帧已进入缓冲区。
* 在发出 `vision-trigger`.
* 不附加帧即可检测摄像头关闭或视频流过期的情况。

***

#### vision-trigger

将缓冲的视觉帧附加到 LLM 上下文中，并可选择触发机器人轮次。仅凭此消息，在视觉功能未启用，或缓冲区为空且没有文本时，绝不会自动附加帧。

```json
{
  "type": "vision-trigger",
  "data": {
    "respond_mode": "auto",
    "text": "屏幕上发生了什么变化？",
    "frame_indices": [-1, -1],
    "update_id": "vision-trigger-1"
  }
}
```

| 字段              | 类型         | 必填 | 默认值            | 说明                                                                                          |
| --------------- | ---------- | -- | -------------- | ------------------------------------------------------------------------------------------- |
| `respond_mode`  | 字符串        | 否  | 会话的默认 `vision` | `"silent"`, `"auto"`，或 `"must_respond"`。显式值无效时会返回错误确认。                                      |
| `text`          | 字符串        | 否  | LLM 运行时的默认视觉提示 | 随帧附加的可选指令。提供此项时，即使缓冲区为空，也可以继续处理纯文本触发请求。                                                     |
| `frame_indices` | integer\[] | 否  | 默认双时间跨度选择      | 缓冲区中保留帧的相对索引。 `-1` 是最新帧。重复索引会合并为一帧。                                                         |
| `frame_ids`     | integer\[] | 否  | —              | 绝对帧呈现时间戳（`attached_frame_pts` / `vision-status` pts 值）。若两者均已设置，则优先使用此项，而非 `frame_indices` 。 |
| `update_id`     | 字符串        | 否  | —              | 客户端关联 ID。会在确认消息中原样返回，并用于重复请求重放。如果未提供，则在顶层消息中 `id` 存在时会使用它。                                  |

**`respond_mode` 取值**

| 值                | 行为                                                             |
| ---------------- | -------------------------------------------------------------- |
| `"silent"`       | 仅附加帧。不调用 LLM。                                                  |
| `"auto"`         | 附加帧，并且仅在机器人处于空闲状态且用户未说话时调用 LLM。否则会静默降级此请求，且不附加帧。               |
| `"must_respond"` | 附加帧并调用 LLM。如果机器人正忙，Convai 会先中断。如果用户正在说话，则附加/预留帧，并在用户轮次结束后作出响应。 |

连接时 `respond_modes.vision` 会将其设为默认值，当 `respond_mode` 未提供。

**成功响应**

```json
{
  "type": "server-response",
  "event_type": "vision-trigger",
  "status": "success",
  "message": "Vision trigger invoked LLM",
  "extras": {
    "requested_respond_mode": "auto",
    "actual_respond_mode": "auto",
    "requested_run_llm": "auto",
    "actual_run_llm": "auto",
    "llm_triggered": true,
    "downgraded": false,
    "downgrade_reason": null,
    "interrupted": false,
    "vision_trigger_outcome": "attached",
    "vision_attach_outcome": "attached",
    "vision_frames_attached": 1,
    "vision_image_tokens_est": 258,
    "attached_frame_pts": [42],
    "frame_binding": "frame_indices",
    "requested_frame_indices": [-1, -1],
    "active_source": "participant-id",
    "active_source_label": "webcam",
    "last_frame_age_ms": 80,
    "update_id": "vision-trigger-1",
    "duplicate": false,
    "vision_buffer": {
      "enabled": true,
      "status": "frames_available",
      "retained_frames": 1
    }
  }
}
```

| 字段                                                | 类型             | 说明                                               |
| ------------------------------------------------- | -------------- | ------------------------------------------------ |
| `requested_respond_mode`                          | 字符串            | 解析后的请求模式，或 `"invalid"`.                          |
| `actual_respond_mode`                             | 字符串            | 经过空闲/忙碌门控后实际应用的模式。                               |
| `requested_run_llm` / `actual_run_llm`            | 字符串            | `"true"`, `"false"`，或 `"auto"`.                  |
| `llm_triggered`                                   | 布尔值            | 是否启动了一个 LLM 回合。                                  |
| `downgraded`                                      | 布尔值            | 请求是否被降级（例如机器人忙碌、缓冲区为空等）。                         |
| `downgrade_reason`                                | string \| null | 适用时，请求被降级的原因。                                    |
| `interrupted`                                     | 布尔值            | `true` 当 `must_respond` 中断了正在进行的机器人回合时。          |
| `vision_trigger_outcome`                          | 字符串            | 触发器的最终结果。                                        |
| `vision_attach_outcome`                           | 字符串            | 选取帧时的附加结果。                                       |
| `vision_frames_attached`                          | 整数             | 附加的帧数。                                           |
| `vision_image_tokens_est`                         | 整数             | 附件的图像令牌估算值。                                      |
| `attached_frame_pts`                              | integer\[]     | 已附加帧的 PTS 值。                                     |
| `frame_binding`                                   | 字符串            | 帧的选择方式（`default`, `frame_indices`, `frame_ids`). |
| `requested_frame_indices` / `requested_frame_ids` | 数组 \| null     | 请求选择字段的回显。                                       |
| `vision_buffer`                                   | 对象             | 处理触发器后的缓冲区快照。                                    |

**常见 `vision_trigger_outcome` 值**

| 值                                                                                                                   | 含义                                 |
| ------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `attached`                                                                                                          | 已附加帧。                              |
| `deduped_stub`                                                                                                      | 帧与上一次附加的帧相同，因此仅添加了占位内容。            |
| `stale_skipped`                                                                                                     | 缓冲区被视为过期，且未提供文本。                   |
| `frames_available`                                                                                                  | 缓冲区中有帧，但触发器未附加帧（例如 `auto` 机器人正忙时）。 |
| `buffer_empty`                                                                                                      | 来源处于活动状态，但没有保留的帧，也没有文本。            |
| `no_active_video`                                                                                                   | 没有活动的视觉来源，也没有文本。                   |
| `vision_not_enabled`                                                                                                | 此会话未启用视觉功能。                        |
| `invalid_respond_mode`                                                                                              | 显式指定的 `respond_mode` 不是允许的值之一。     |
| `frame_id_evicted` / `invalid_frame_ids` / `invalid_frame_indices` / `invalid_frame_indices_range` / `rate_limited` | 帧绑定失败。                             |

`update_id` 可确保重试安全：重复的 `vision-status` 或 `vision-trigger` 若使用相同 ID，则会重放先前的确认，其中包含 `"duplicate": true` 且不会再次附加内容或触发操作。

**使用场景：**

* 让角色评论当前摄像头或屏幕画面。
* 静默预热视觉上下文（`respond_mode: "silent"`) 在后续用户轮次之前。
* 通过以下方式重新附加指定的近期帧： `frame_indices` 或 `frame_ids`.

***

### 音频控制

#### tts-toggle

启用或禁用机器人通过文本转语音生成的音频输出。

```json
{
  "type": "tts-toggle",
  "data": {
    "enabled": true
  }
}
```

| 字段        | 类型  | 必填 | 说明                                     |
| --------- | --- | -- | -------------------------------------- |
| `enabled` | 布尔值 | 是  | `true` 以启用 TTS 输出。 `false` 以禁用 TTS 输出。 |

**服务器响应附加字段：**

| 字段        | 类型  | 说明           |
| --------- | --- | ------------ |
| `enabled` | 布尔值 | 从请求中回显的启用状态。 |

**使用场景：**

* 在过场动画或旁白片段期间将机器人音频静音。
* 根据无障碍需求切换音频输出。

***

#### stt-toggle

将语音转文本的麦克风输入处理设为静音或取消静音。

```json
{
  "type": "stt-toggle",
  "data": {
    "muted": true
  }
}
```

| 字段      | 类型  | 必填 | 说明                           |
| ------- | --- | -- | ---------------------------- |
| `muted` | 布尔值 | 是  | `true` 以停止监听。 `false` 以恢复监听。 |

**服务器响应附加字段：**

| 字段      | 类型  | 说明           |
| ------- | --- | ------------ |
| `muted` | 布尔值 | 从请求中回显的静音状态。 |

**使用场景：**

* 按钮未按住时将 STT 设为静音，以实现按键通话输入。
* 在不应处理用户语音的时段禁用语音输入。

***

#### interrupt-bot

立即停止机器人当前的语音播放。

```json
{
  "type": "interrupt-bot"
}
```

否 `data` 必须提供 payload。

**使用场景：**

* 允许用户在机器人说话过程中打断它。
* 当场景内事件要求保持静音时，立即停止机器人音频。

***

#### force-user-stopped-speaking

向服务器指示用户已结束说话。在按键通话实现中使用此消息，显式结束语音片段。

```json
{
  "type": "force-user-stopped-speaking"
}
```

否 `data` 必须提供 payload。

**使用场景：**

* 松开按键通话按钮时，发送语音结束信号。
* 未使用 VAD 时，手动发送语音结束信号。

***

### 会话管理

#### reset-idle-timer

重置用户空闲超时倒计时。发送此消息以表示用户正在活动，避免因空闲而断开连接。

```json
{
  "type": "reset-idle-timer",
  "data": {}
}
```

否 `data` 必须提供 payload。服务器会忽略任何 `data` 内容。

**使用场景：**

* 当用户执行点击或按键等 UI 操作时，重置计时器。
* 检测语音交互之外的用户活动（例如鼠标移动），并防止空闲超时。
* 在较长时间的非语音交互期间保持会话活跃。

***

#### usage-toggle

启用或禁用向此客户端推送信息类 `usage-update` 消息。

```json
{
  "type": "usage-toggle",
  "data": {
    "enabled": true
  }
}
```

| 字段        | 类型  | 必填 | 说明                                            |
| --------- | --- | -- | --------------------------------------------- |
| `enabled` | 布尔值 | 是  | `true` 恢复 `usage-update` 流式传输， `false` 则停止传输。 |

这只控制服务器是否向客户端推送用量消息，不会影响用量跟踪、汇总或计费。 `usage-update` 消息仅在会话以调试模式运行且启用了用量跟踪时可用。

**使用场景：**

* 隐藏调试用量面板时，停止实时费用流。
* 对于不显示实时用量的客户端，减少数据通道流量。

***

#### kill-pipeline

终止会话并关闭连接。

```json
{
  "type": "kill-pipeline"
}
```

否 `data` 必须提供 payload。

**使用场景：**

* 用户退出体验时，正常结束会话。
* 无需等待空闲超时即可释放资源。

***

### 后续步骤

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

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

{% content-ref url="/pages/29ba5f52bd1ff6aac10fb390cafb074f474ab066" %}
[音频数据（通过数据通道）](https://docs.convai.com/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 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/client-to-server-messages.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.
