消息词汇表

Convai Live API 中所有可用消息类型的完整词汇表，用于客户端与服务器之间的实时通信。

概述

本术语表为 Convai Live API 中使用的所有消息类型提供了全面参考。消息通过 WebRTC 数据通道在您的客户端应用与 Convai 服务器之间双向传输。

---

消息方向

方向	描述
客户端 → 服务器	您发送的消息，用于触发操作、更新状态或控制机器人
服务器 → 客户端	您接收的消息，用于事件、状态变更和实时数据

---

消息格式

客户端 → 服务器消息

从客户端发送到服务器的消息使用以下结构：

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

• type （字符串，必填）：消息类型标识符
• data （对象，可选）：消息负载（结构因类型而异）

服务器 → 客户端消息

从服务器发送到客户端的消息会封装在 RTVI 信封中：

{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "<message-type>",
    ...payload fields
  }
}

• label （字符串）：始终为 "rtvi-ai"
• type （字符串）：始终为 "server-message" 用于自定义服务器消息
• data （对象）：包含其自身的实际消息 type 以及负载字段

在详细消息文档页面中，为了清晰起见，示例只展示内部 data 负载。

---

服务器响应消息

对于每个客户端到服务器的消息，服务器都会自动发送一条 server-response 消息，用于确认接收并指示处理状态。这类似于 REST API 中的 HTTP 响应码。

响应示例：

{
  "type": "server-response",
  "event_type": "context-update",
  "status": "success",
  "message": "Context updated successfully (append mode)",
  "extras": {
    "token_count": 1523,
    "max_tokens": 50000,
    "remaining_tokens": 48477
  }
}

字段	类型	描述
event_type	字符串	触发此响应的原始客户端消息类型
status	字符串	处理状态： "success", "error", "processing", "pending"
message	字符串	结果的人类可读描述（可选）
extras	对象	附加的、特定事件的数据（可选）

状态值：

• "success" - 消息已成功处理
• "error" - 发生错误（请参见 message 以了解详情）
• "processing" - 消息正在异步处理
• "pending" - 已收到消息，但处理延迟

---

客户端 → 服务器消息

消息类型	用途	详情页
trigger-message	触发叙事事件或发送上下文	client-to-server-messages.md
user_text_message	将文本输入作为用户发送	client-to-server-messages.md
update-template-keys	更新提示模板变量	client-to-server-messages.md
update-scene-metadata	更新场景对象	client-to-server-messages.md
update-dynamic-info	更新动态上下文（基础）	client-to-server-messages.md
context-update	更新运行时上下文（含模式控制）	client-to-server-messages.md
tts-toggle	启用/禁用机器人音频	client-to-server-messages.md
stt-toggle	静音/取消静音语音识别	client-to-server-messages.md
interrupt-bot	立即停止机器人发言	client-to-server-messages.md
force-user-stopped-speaking	标记用户语音结束（按住说话）	client-to-server-messages.md
reset-idle-timer	重置空闲超时监控	client-to-server-messages.md

---

服务器 → 客户端消息

消息类型	用途	格式	详情页
server-response	每条客户端消息的响应	直接（旧版）	server-to-client-messages.md
interaction-created	已创建交互 ID	服务器消息封装	server-to-client-messages.md
usage-limit-reached	配额超出通知	服务器消息封装	server-to-client-messages.md
bot-turn-completed	机器人发言结束	服务器消息封装	server-to-client-messages.md
bot-emotion	头像的机器人情绪	服务器消息封装	server-to-client-messages.md
behavior-tree-response	行为树数据	服务器消息封装	server-to-client-messages.md
moderation-response	内容审核结果	服务器消息封装	server-to-client-messages.md
action-response	要触发的动作/动画	服务器消息封装	server-to-client-messages.md
final-user-transcription	用户语音转录	服务器消息封装	server-to-client-messages.md
visemes	口型同步数据	服务器消息封装	server-to-client-messages.md
neurosync-blendshapes	面部动画数据	服务器消息封装	server-to-client-messages.md
chunked-neurosync-blendshapes	批量面部动画	服务器消息封装	server-to-client-messages.md
blendshape-turn-stats	轮次统计	服务器消息封装	server-to-client-messages.md
user-idle-warning	空闲超时警告	服务器消息封装	server-to-client-messages.md
llm-no-response	LLM 选择不响应	服务器消息封装	server-to-client-messages.md
audio-data	通过数据通道传输的音频片段（自定义模式）	服务器消息封装	参见 通过数据通道传输的音频数据

格式键：

• 服务器消息封装：使用完整的 RTVI 信封格式，其中 "type": "server-message" 以及事件数据嵌套在 data.type 及后续字段中
• 直接（旧版）：使用 data 作为一个扁平对象，将事件类型和字段放在顶层

所有客户端消息都会收到一条 server-response 确认，其中包含成功/错误状态和附加数据。

---

按事件类型划分的常见响应附加字段

当您收到一条 server-response 消息时， extras 字段可能包含特定于事件的数据：

事件类型	附加字段
context-update	token_count, max_tokens, remaining_tokens, content
tts-toggle	enabled
stt-toggle	muted
trigger-message	trigger_name, has_speak_tag
user_text_message	text

---

错误响应示例

无效 JSON

{
  "type": "server-response",
  "event_type": "parse-error",
  "status": "error",
  "message": "Failed to parse message: invalid JSON or UTF-8 encoding"
}

缺少类型字段

{
  "type": "server-response",
  "event_type": "validation-error",
  "status": "error",
  "message": "Message missing required 'type' field"
}

未知消息类型

{
  "type": "server-response",
  "event_type": "unknown-message-type",
  "status": "error",
  "message": "Unknown message type: unknown-message-type",
  "extras": {
    "supported_types": ["trigger-message", "context-update", "tts-toggle", ...]
  }
}

---

消息类别

上下文与状态管理

用于管理对话上下文和机器人状态的消息：

• context-update - 统一的、带模式控制的上下文更新
• update-dynamic-info - 基础动态上下文更新
• update-template-keys - 更新提示模板变量
• update-scene-metadata - 更新场景对象描述

音频控制

用于控制音频输入和输出的消息：

• tts-toggle - 启用/禁用文本转语音输出
• stt-toggle - 静音/取消静音语音转文本输入
• interrupt-bot - 中断当前机器人发言
• force-user-stopped-speaking - 标记用户语音结束

交互与事件

用于触发事件和发送用户输入的消息：

• trigger-message - 触发叙事事件或上下文相关动作
• user_text_message - 以用户输入发送文本

会话管理

用于管理会话生命周期的消息：

• reset-idle-timer - 重置空闲超时

动画与视觉反馈

包含动画和视觉数据的消息：

• bot-emotion - 用于头像表情的情绪数据
• visemes - 口型同步 blendshape 数据
• neurosync-blendshapes - 面部动画 blendshape（单帧）
• chunked-neurosync-blendshapes - 批量面部动画 blendshape
• action-response - 要执行的动作和动画

转录与文本

包含文本和转录数据的消息：

• final-user-transcription - 用户语音的最终转录

系统事件

关于系统状态和事件的消息：

• server-response - 客户端消息确认
• interaction-created - 已创建会话交互 ID
• bot-turn-completed - 机器人轮次完成
• usage-limit-reached - 已超出使用配额
• user-idle-warning - 用户空闲超时警告
• llm-no-response - LLM 选择不响应

语音活动检测

来自基于 VAD 的 STT 门控系统的消息：

• vad-stt-started - STT 服务开始转录
• vad-stt-stopped - STT 服务停止转录
• vad-stt-debug - VAD 调试事件（仅调试模式）

---

相关文档

• Connect API - 建立实时会话
• 客户端到服务器消息 - 详细的客户端消息参考
• 服务器到客户端消息 - 详细的服务器消息参考
• 通过数据通道传输的音频数据 - 自定义音频处理
• 指标 - 性能指标和监控

---