客户端到服务器消息

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

所有客户端到服务器的消息都通过在成功建立后创建的 WebRTC 数据通道以 JSON 发送 /connect 通话。有关消息格式约定、服务器返回的状态码，以及双向所有消息类型的完整索引，请参见 消息术语表.

消息信封

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

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

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

服务器会用一个 服务器响应 消息。参见 服务器响应 下方。

服务器响应

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

{
  "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

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

{
  "type": "trigger-message",
  "data": {
    "trigger_name": "greeting",
    "trigger_message": "用户进入了房间"
  }
}

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

用例：

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

服务器响应附加字段：

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

---

user_text_message

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

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

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

服务器响应附加字段：

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

---

上下文与状态

update-template-keys

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

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

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

用例：

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

---

update-scene-metadata

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

{
  "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 若要替换语义动作对象，请重新连接；或在更改 v2 客户端工具声明时重新连接。

---

update-dynamic-info

更新注入到机器人系统提示中的动态信息。用于基本的单字段上下文更新。对于带有令牌预算跟踪的模式控制更新，请使用 context-update 改为此项。

{
  "type": "update-dynamic-info",
  "data": {
    "dynamic_info": {
      "text": "用户完成了屠龙任务并获得了一把金色长剑。"
    }
  }
}

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

---

context-update

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

{
  "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中的字段。仅替换你提供的列表——只发送 对象 离开 动作 和 characters 不会受影响。当场景变化且角色的语义可行性也随之变化时使用此项。

action_config.tools 按连接范围生效。一个 context-update 其中包含 tools 会返回错误；请重新连接以替换客户端工具声明。向 scene_description 或 文本 添加对象并不会使其成为语义动作目标。参见 响应契约与解析.

模式值

值	行为
"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:

{
  "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":

{
  "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 投影。

{
  "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 秒等待每个结果。超时调用会变为失效，迟到的结果会被拒绝。

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

{
  "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上设置。这些 RTVI 控制消息本身不会发布图像字节。

vision-status

在不附加帧或触发 LLM 的情况下查询当前视觉缓冲区状态。请在启用视觉之后、关闭摄像头之后，或在需要确认帧可用后再调用时使用此项。 vision-trigger.

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

字段	类型	必需	说明
update_id	字符串	否	客户端关联 ID。会在确认中回显，并用于重复重放。若省略，则使用顶层消息 ID 在存在时使用。

成功响应

{
  "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 上下文中，并可选地触发一次机器人回合。仅靠此消息，在视觉被禁用或缓冲区为空且没有文本时，帧绝不会自动附加。

{
  "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 被省略。

成功响应

{
  "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

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

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

字段	类型	必需	说明
enabled	布尔值	是	是 以启用 TTS 输出。 否 以禁用它。

服务器响应附加字段：

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

用例：

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

---

stt-toggle

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

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

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

服务器响应附加字段：

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

用例：

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

---

interrupt-bot

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

{
  "type": "interrupt-bot"
}

否 data 需要负载。

用例：

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

---

force-user-stopped-speaking

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

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

否 data 需要负载。

用例：

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

---

会话管理

reset-idle-timer

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

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

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

用例：

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

---

usage-toggle

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

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

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

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

用例：

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

---

kill-pipeline

终止会话并关闭连接。

{
  "type": "kill-pipeline"
}

否 data 需要负载。

用例：

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

---

下一步

消息术语表连接 API音频数据（通过数据通道）