> 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 服务器的所有消息，包括载荷、字段和响应细节。

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

### 消息信封

每条客户端到服务器的消息都使用此信封：

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

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

服务器会用一个 `服务器响应` 消息。参见 [服务器响应](#server-response) 下方。

### 服务器响应

服务器会发送一个 `服务器响应` 消息，以响应其收到的每一条客户端到服务器消息，不论类型。

```json
{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "success",
  "message": "TTS 已启用",
  "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": "用户进入了房间"
  }
}
```

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

**用例：**

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

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

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

***

#### user\_text\_message

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

```json
{
  "type": "user_text_message",
  "data": {
    "text": "你好，你怎么样？"
  }
}
```

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

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

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

***

### 上下文与状态

#### update-template-keys

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

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

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

**用例：**

* 更新动态提示变量，例如玩家名称、属性或游戏状态。
* 根据当前会话状态自定义机器人的响应。

***

#### update-scene-metadata

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

```json
{
  "type": "update-scene-metadata",
  "data": {
    "scene_metadata": [
      { "name": "torch", "description": "墙上的一支燃烧火把" },
      { "name": "door", "description": "一扇上锁的木门" },
      { "name": "chest", "description": "一个古老的宝箱" }
    ]
  }
}
```

| 字段                                  | 类型    | 必需 | 说明          |
| ----------------------------------- | ----- | -- | ----------- |
| `data.scene_metadata`               | 对象\[] | 是  | 要描述的场景对象数组。 |
| `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": "用户完成了屠龙任务并获得了一把金色长剑。"
    }
  }
}
```

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

***

#### context-update

可完全控制模式、令牌预算和 LLM 触发，更新机器人的运行时动态上下文。这是运行时上下文管理的首选消息。

```json
{
  "type": "context-update",
  "data": {
    "text": "新上下文信息",
    "mode": "append",
    "run_llm": "auto",
    "current_attention_object": "torch",
    "action_config": {
      "objects": [
        { "name": "torch", "description": "墙上的一支燃烧火把" }
      ]
    },
    "remove_static": false
  }
}
```

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

**会话中途更新动作可行性**

`action_config` 接受语义 `动作`, `对象`, `characters`以及 `current_attention_object` 来自 [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md#request-body)中的字段。仅替换你提供的列表——只发送 `对象` 离开 `动作` 和 `characters` 不会受影响。当场景变化且角色的语义可行性也随之变化时使用此项。

`action_config.tools` 按连接范围生效。一个 `context-update` 其中包含 `tools` 会返回错误；请重新连接以替换客户端工具声明。向 `scene_description` 或 `文本` 添加对象并不会使其成为语义动作目标。参见 [响应契约与解析](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/response-contract-and-parsing.md).

**模式值**

| 值           | 行为                                                      |
| ----------- | ------------------------------------------------------- |
| `"append"`  | 新增 `文本` 到现有的运行时动态上下文。                                   |
| `"replace"` | 用以下内容替换现有运行时动态上下文： `文本`.                                |
| `"reset"`   | 清除运行时动态上下文。若 `remove_static` 是 `是`. `文本` 不需要，也会清除静态上下文。 |

**run\_llm 值**

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

**令牌预算**

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

| 分区                                 | 预算           |
| ---------------------------------- | ------------ |
| `static_text` 在连接时提供的会话级上下文        | 20,000 个估算令牌 |
| Runtime `文本` 来自 `append` 和 `替换` 更新 | 30,000 个估算令牌 |
| 合并动态上下文                            | 50,000 个估算令牌 |

当运行时 `文本` 超过其 30,000 令牌预算时，Convai 会裁剪最旧的运行时上下文更新，并保留符合预算的最新更新。

`static_text` 是为此连接提供的会话和环境上下文。它会在以下操作之间保留： `reset` 调用，除非 `remove_static` 是 `是`.

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

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

**成功响应**

成功时，服务器会返回一个 `服务器响应` 并带有以下 `extras`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "上下文更新成功（追加模式）",
  "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": "此处为完整上下文文本..."
  }
}
```

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

旧版 `word_count`, `static_word_count`, `runtime_word_count`, `max_words`以及 `remaining_words` 旧版客户端中可能会出现这些字段。令牌字段为权威字段。

**错误响应**

当超过令牌上限时，服务器会返回一个 `服务器响应` 与 `"status": "error"`:

```json
{
  "type": "server-response",
  "event_type": "context-update",
  "status": "error",
  "message": "处理 context-update 失败：DynamicInfo 存在 1 个校验错误\n值错误，动态信息 static_text 令牌上限已超出。static_text：20001 个估算令牌，最大值：20000 个令牌。"
}
```

* 校验检查会独立应用于静态、运行时和合并的估算令牌上限。
* 当合并动态上下文超过 40,000 个估算令牌时，Convai 会记录一条服务器端警告。
* 错误消息会包含两个分区的估算令牌明细。

***

### 代理式动作结果

#### action-result

为客户端执行的工具调用返回一个终端结果。此消息需要动作协议 v2，并与以下项对应： `ID` 在一个 `工具调用` 项或 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"`，或 `"已取消"`. |
| `output`               | JSON 值 | 否  | 结果数据。与 `"completed"` 配合使用，当模型需要该操作的输出时。   |
| `错误`                   | JSON 值 | 否  | 失败或取消的详细信息。已完成的结果不能包含此字段。                 |
| `character_session_id` | 字符串    | 否  | 会话保护。当存在时，必须与当前活动的角色会话匹配。                 |

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

候选实现允许的最大序列化结果大小为 `64 KiB`。它最多允许 `8` 个未完成调用，以及最多 `8` 轮工具结果续接回合用于一次用户轮次。Convai 默认等待 `60` 秒等待每个结果。超时调用会变为失效，迟到的结果会被拒绝。

被接受的结果会产生如下确认：

```json
{
  "type": "server-response",
  "event_type": "action-result",
  "status": "success",
  "message": "工具结果已接受",
  "extras": {
    "tool_call_id": "call_abc123",
    "idempotent": false
  }
}
```

对同一项重试相同的终端负载 `ID` 会被接受，并返回 `extras.idempotent: true`。向已完成的 `ID` 返回 `conflicting_terminal_tool_result`。未知、失效、跨会话、过大以及参与者不匹配的结果会返回错误 `服务器响应` 与 `extras.error_code` 以及（如可用） `extras.tool_call_id`.

在接受结果后，Convai 会将其提供给同一模型上下文，以便继续生成。该确认并不是排序屏障；续接输出可能会先于其 `服务器响应`。不同调用可以并行未完成。不要据此推断 SDK 或 Convai 按顺序执行了它们。

***

### 视觉

视觉消息会查询或消费会话的视觉环形缓冲区。帧会在以下条件下从 WebRTC 视频轨道（LiveKit）进入该缓冲区： `vision_input_config` 已在 [`/connect`](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md)上设置。这些 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": "视觉状态",
  "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`         | 字符串 \| null | 当有源处于活动状态时，所选参与者 ID。           |
| `active_source_label`   | 字符串 \| null | 人类可读的源标签，如已知。                  |
| `last_frame_age_ms`     | 整数 \| 空     | 最新保留帧的年龄（毫秒）。                  |
| `vision_buffer`         | 对象          | 客户端安全的环形缓冲区快照。绝不包含图像字节。        |
| `update_id`             | 字符串         | 在请求中提供时会回显。                    |
| `duplicate`             | 布尔值         | `是` 当此确认是先前内容的重放时 `update_id`. |

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

| 值            | 含义                  |
| ------------ | ------------------- |
| `有可用帧`       | 源处于活动状态，并且缓冲区已有保留帧。 |
| `缓冲区为空`      | 源处于活动状态，但尚未保留任何帧。   |
| `无活动视频`      | 未选择活动的视觉源。          |
| `未启用 vision` | 此会话未启用视觉。           |

**用例：**

* 确认在用户启用摄像头或屏幕共享后帧已进入。
* 在发出之前检查缓冲区深度 / 采样窗口 `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"`。无效的显式值会返回错误确认。                                |
| `文本`            | 字符串   | 否  | LLM 运行时的默认视觉提示     | 与帧一起附加的可选指令。存在时，即使缓冲区为空，纯文本触发也仍可继续。                                                   |
| `frame_indices` | 整数\[] | 否  | 默认双时域选择            | 保留缓冲区中的相对索引。 `-1` 是最新帧。重复索引会合并为一帧。                                                    |
| `frame_ids`     | 整数\[] | 否  | —                  | 帧的绝对展示时间戳（`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": "视觉触发已调用 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],
    "帧绑定": "帧索引",
    "请求的帧索引": [-1, -1],
    "active_source": "participant-id",
    "active_source_label": "webcam",
    "最后一帧年龄_ms": 80,
    "更新ID": "vision-trigger-1",
    "duplicate": false,
    "vision_buffer": {
      "enabled": true,
      "status": "frames_available",
      "保留的帧数": 1
    }
  }
}
```

| 字段                      | 类型          | 说明                                          |
| ----------------------- | ----------- | ------------------------------------------- |
| `请求的响应模式`               | 字符串         | 已解析的请求模式，或 `"无效"`.                          |
| `实际响应模式`                | 字符串         | 在空闲/忙碌门控后实际应用的模式。                           |
| `请求运行 LLM` / `实际运行 LLM` | 字符串         | `"true"`, `"false"`，或 `"auto"`.             |
| `已触发 LLM`               | 布尔值         | 是否已开始一次 LLM 回合。                             |
| `已降级`                   | 布尔值         | 请求是否被降级（机器人忙碌、缓冲区为空等）。                      |
| `降级原因`                  | 字符串 \| null | 在适用时，请求为何被降级。                               |
| `已中断`                   | 布尔值         | `是` 当 `必须响应` 中断了一个进行中的机器人回合。                |
| `视觉触发结果`                | 字符串         | 触发的最终结果。                                    |
| `视觉附加结果`                | 字符串         | 选择帧时的附加结果。                                  |
| `已附加的视觉帧`               | 整数          | 附加的帧数量。                                     |
| `视觉图像 token 估算`         | 整数          | 为此次附加估算的图像 token 数。                         |
| `attached_frame_pts`    | 整数\[]       | 已附加帧的 PTS 值。                                |
| `帧绑定`                   | 字符串         | 帧的选择方式（`默认`, `frame_indices`, `frame_ids`). |
| `请求的帧索引` / `请求的帧 ID`    | 数组 \| null  | 对请求选择字段的回显。                                 |
| `vision_buffer`         | 对象          | 处理触发后的缓冲区快照。                                |

**通用 `视觉触发结果` 值**

| 值                                                               | 含义                              |
| --------------------------------------------------------------- | ------------------------------- |
| `已附加`                                                           | 已附加帧。                           |
| `去重占位`                                                          | 帧与上次附加匹配，并被置为占位。                |
| `已跳过过期项`                                                        | 缓冲区被视为已过期，且未提供文本。               |
| `有可用帧`                                                          | 缓冲区中有帧，但触发未附加（例如 `自动` 在机器人忙碌时）。 |
| `缓冲区为空`                                                         | 来源处于活动状态，没有保留帧，也没有文本。           |
| `无活动视频`                                                         | 没有活动的视觉来源，也没有文本。                |
| `未启用 vision`                                                    | 会话未启用视觉功能。                      |
| `无效响应模式`                                                        | 显式 `respond_mode` 不是允许的值之一。     |
| `frame_id_evicted` / `无效的帧 ID` / `无效帧索引` / `无效的帧索引范围` / `受速率限制` | 帧绑定失败。                          |

`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` | 布尔值 | 是  | `是` 以启用 TTS 输出。 `否` 以禁用它。 |

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

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

**用例：**

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

***

#### stt-toggle

将语音转文字麦克风输入处理静音或取消静音。

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

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

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

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

**用例：**

* 当按钮未按住时，通过将 STT 静音来实现按键通话输入。
* 在不应处理用户语音的时刻禁用语音输入。

***

#### interrupt-bot

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

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

否 `data` 需要负载。

**用例：**

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

***

#### force-user-stopped-speaking

向服务器指示用户已说完。请在按键通话实现中使用此项，以明确结束语音片段。

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

否 `data` 需要负载。

**用例：**

* 当按键通话按钮释放时发送语音结束信号。
* 在未使用 VAD 时提供手动语音结束信号。

***

### 会话管理

#### reset-idle-timer

重置用户空闲超时倒计时。发送此项以表示用户活动并防止空闲断开连接。

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

否 `data` 需要负载。服务器会忽略任何 `data` 内容。

**用例：**

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

***

#### usage-toggle

启用或禁用信息类 `usage-update` 消息流式传输到此客户端。

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

| 字段        | 类型  | 必需 | 说明                                   |
| --------- | --- | -- | ------------------------------------ |
| `enabled` | 布尔值 | 是  | `是` 恢复 `usage-update` 流式传输， `否` 停止它。 |

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

**用例：**

* 当调试用量面板隐藏时停止实时成本流。
* 为不渲染实时用量的客户端减少数据通道流量。

***

#### kill-pipeline

终止会话并关闭连接。

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

否 `data` 需要负载。

**用例：**

* 当用户退出体验时，干净地结束会话。
* 释放资源而无需等待空闲超时。

***

### 下一步

{% 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" %}
[连接 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, and the optional `goal` query parameter:

```
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=<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.