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

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

服务器会用一个 `server-response` 消息来确认每条客户端消息。参见 [服务器响应](#server-response) 下文。

### 服务器响应

服务器会为它收到的每一条从客户端到服务器的消息发送一个 `server-response` 消息，无论类型如何。

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

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

**状态值：**

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

***

### 交互与事件

#### trigger-message

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

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

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

**使用场景：**

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

**服务器响应附加信息：**

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

***

#### user\_text\_message

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

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

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

**服务器响应附加信息：**

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

***

### 上下文与状态

#### 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`        | string    | 是  | 对象标识符。      |
| `data.scene_metadata[].description` | string    | 是  | 对象的人类可读描述。  |

**使用场景：**

* 在环境变化时更新场景中的可交互对象。
* 在不修改动作可供性的情况下，调整机器人对环境的上下文。

`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` | string | 是  | 要注入系统提示词的动态上下文文本。 |

***

#### 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`                     | string | 是，除非 `mode` 是 `“reset”` | —          | 要应用的上下文文本。                               |
| `mode`                     | string | 否                       | `“append”` | 如何应用上下文。                                 |
| `run_llm`                  | string | 否                       | `"auto"`   | 更新后是否触发 LLM 回复。                          |
| `current_attention_object` | 字符串或对象 | 否                       | —          | 更新活动关注对象以进行动作引用锚定。                       |
| `action_config`            | 对象     | 否                       | —          | 替换当前会话中提供的动作可供性列表。见下文。                   |
| `remove_static`            | 布尔值    | 否                       | `false`    | 对于 `“reset”` 仅限 mode：当 `true`时，也清除静态上下文。 |

**在会话中途更新动作可供性**

`action_config` 接受语义 `actions`, `objects`, `characters`，以及 `current_attention_object` 字段来自 [连接 API](/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` 并不会使其成为语义动作目标。参见 [响应契约与解析](/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`. `text` 则会清除运行时动态上下文。若 |

**不需要，也会清除静态上下文。**

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

**令牌预算**

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

| 分区                             | 预算           |
| ------------------------------ | ------------ |
| `static_text` （连接时提供的会话级上下文）   | 20,000 个估算令牌 |
| 运行时 `text` （来自 `追加` 和 `替换` 更新） | 30,000 个估算令牌 |
| 合并后的动态上下文                      | 50,000 个估算令牌 |

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

`static_text` 是为此连接提供的会话和环境上下文。它会在 `重置` 调用之间保留，除非 `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": "上下文已成功更新（追加模式）",
  "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`         | 整数     | 当前动态上下文中的估算令牌总数。           |
| `static_token_count`  | 整数     | 来自静态动态上下文的估算令牌数。           |
| `runtime_token_count` | 整数     | 来自运行时动态上下文的估算令牌数。          |
| `max_tokens`          | 整数     | 合并后的动态上下文预算（50,000 个估算令牌）。 |
| `static_max_tokens`   | 整数     | 静态动态上下文预算（20,000 个估算令牌）。   |
| `runtime_max_tokens`  | 整数     | 运行时动态上下文预算（30,000 个估算令牌）。  |
| `remaining_tokens`    | 整数     | 在达到合并上限之前剩余的估算令牌数。         |
| `content`             | string | 保留的完整运行时动态上下文文本。           |

旧版 `word_count`, `static_word_count`, `runtime_word_count`, `max_words`，以及 `remaining_words` 字段可能会出现在较旧的客户端中。令牌字段才是权威依据。

**错误响应**

当超出令牌限制时，服务器会返回一个 `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."
}
```

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

***

### 代理式动作结果

#### action-result

为客户端执行的工具调用返回一个终态结果。此消息需要动作协议 v2，并与 `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`                   | string | 是  | 来自工具调用的关联 ID。长度为 `1`–`256` 个字符。                 |
| `状态`                   | string | 是  | 终态状态： `"completed"`, `"error"`，或 `"cancelled"`. |
| `output`               | JSON 值 | 否  | 结果数据。与 `"completed"` 一起使用，当模型需要该操作的输出时。         |
| `错误`                   | JSON 值 | 否  | 失败或取消详情。已完成的结果不能包含此字段。                          |
| `character_session_id` | string | 否  | 会话保护。存在时，必须与当前角色会话匹配。                           |

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` 返回 `发送不同的终态载荷会导致`冲突终态工具结果 `server-response` 并将 `extras.error_code` ，如有可用，还包括 `extras.tool_call_id`.

在接受结果后，Convai 会将其提供给相同的模型上下文，以便生成可以继续。该确认不是顺序屏障；续写输出可能在其 `server-response`之前到达。不同调用可以并行处于未完成状态。不要据此推断 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` | string | 否  | 客户端关联 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` | string      | 高级别缓冲区结果。                   |
| `active_source`         | 字符串 \| null | 当有源处于活动状态时，所选参与者 ID。        |
| `active_source_label`   | 字符串 \| null | 人类可读的来源标签，如已知。              |
| `last_frame_age_ms`     | 整数 \| null  | 最新保留帧的年龄（毫秒）。               |
| `vision_buffer`         | 对象          | 客户端安全的环形缓冲区快照。绝不包含图像字节。     |
| `update_id`             | string      | 在请求中提供时会回显。                 |
| `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`  | string | 否  | 以下的会话默认值： `视觉` | `"silent"`, `"auto"`，或 `"must_respond"`。无效的显式值会返回错误确认。                               |
| `text`          | string | 否  | LLM 运行时的默认视觉提示 | 随帧附带的可选指令。存在时，即使缓冲区为空，纯文本触发器仍可继续。                                                    |
| `frame_indices` | 整数\[]  | 否  | 默认双时间范围选择      | 保留缓冲区中的相对索引。 `-1` 是最新帧。重复索引会合并为一帧。                                                   |
| `frame_ids`     | 整数\[]  | 否  | —              | 绝对帧展示时间戳（`attached_frame_pts` / `vision-status` pts 值）。优先于 `frame_indices` 当两者都已设置时。 |
| `update_id`     | string | 否  | —              | 客户端关联 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],
    "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
    }
  }
}
```

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

**常见 `视觉触发结果` 值**

| 值                                                      | 含义                             |
| ------------------------------------------------------ | ------------------------------ |
| `已附加`                                                  | 帧已附加。                          |
| `去重占位`                                                 | 帧与上一次附加相匹配，因此被占位处理。            |
| `过期跳过`                                                 | 缓冲区被视为过期，并且未提供文本。              |
| `frames_available`                                     | 缓冲区有帧，但触发器未附加（例如 `自动` 机器人忙碌时）。 |
| `buffer_empty`                                         | 源处于活动状态，没有保留的帧，也没有文本。          |
| `no_active_video`                                      | 没有活动的视觉源，也没有文本。                |
| `vision_not_enabled`                                   | 该会话未启用视觉功能。                    |
| `无效的响应模式`                                              | 显式 `respond_mode` 不是允许的值之一。    |
| `帧 ID 已驱逐` / `无效的帧 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` | 布尔值 | 是  | `true` 以启用 TTS 输出。 `false` 以禁用它。 |

**服务器响应附加信息：**

| 字段        | 类型  | 说明           |
| --------- | --- | ------------ |
| `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" %}
[消息术语表](/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 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.