服务器到客户端消息

Convai 在 Live API 中通过 WebRTC 数据通道发送给客户端的所有消息完整参考，包括字段、类型和建议操作。

Convai Live API 服务器在活动会话期间通过 WebRTC 数据通道发送这些消息。每种消息类型都表示一个不同事件——确认、机器人状态变化、动画数据或会话限制。请参见 消息术语表 以查看所有消息类型及其信封格式的摘要。

除 server-response 外，所有服务器消息都使用在 interaction-created下所示的 RTVI 信封格式。本页后续示例仅展示内部的 数据 载荷，以便更清晰。

---

确认

server-response

server-response 会在每条客户端到服务器消息后发送，用于确认收到并报告处理结果。它使用 直接（旧版）格式 ——不是 RTVI 信封——，因此字段会出现在 JSON 对象的顶层，而不是嵌套在 数据.

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

字段	类型	说明
类型	string	始终 "server-response"
事件类型	string	触发此响应的客户端消息类型
状态	string	处理状态： "success", "error", "processing"，或 "pending"
message	字符串 | 空值	结果的人类可读描述
附加信息	对象 | 空值	其他特定于事件的数据

状态值

值	含义
"success"	消息处理成功
"error"	发生错误；请参见 message ，详见
"processing"	消息正在异步处理中
"pending"	消息已收到，但处理延迟

附加信息 按事件类型划分的字段

事件类型	附加信息 字段
上下文更新	token_count, static_token_count, runtime_token_count, max_tokens, static_max_tokens, runtime_max_tokens, remaining_tokens, 内容
tts-toggle	已启用
stt-toggle	muted
触发消息	trigger_name, has_speak_tag
user_text_message	text

错误示例

{
  "type": "server-response",
  "event_type": "tts-toggle",
  "status": "error",
  "message": "TTS 绕过过滤器不可用"
}

验证错误 — 无效的 JSON

{
  "type": "server-response",
  "event_type": "parse-error",
  "status": "error",
  "message": "解析消息失败：JSON 无效或 UTF-8 编码错误"
}

验证错误 — 缺少 type 字段

{
  "type": "server-response",
  "event_type": "validation-error",
  "status": "error",
  "message": "消息缺少必需的 'type' 字段"
}

验证错误 — 未知消息类型

{
  "type": "server-response",
  "event_type": "unknown-message-type",
  "status": "error",
  "message": "未知消息类型：unknown-message-type",
  "extras": {
    "supported_types": ["trigger-message", "context-update", "tts-toggle"]
  }
}

建议操作： 请查看 状态 字段出现在每个 server-response响应中。处理 "error" 响应时，读取 message 并更新你的 UI。使用 附加信息 字段来反映当前状态——例如，在 事件类型 为 stt-toggle.

---

会话与生命周期

interaction-created

在会话生命周期早期发送，此时已创建 interaction ID。这是第一条携带完整 RTVI 信封的消息。

完整的 RTVI 信封

{
  "label": "rtvi-ai",
  "type": "server-message",
  "data": {
    "type": "interaction-created",
    "interaction_id": "int_abc123def456",
    "character_session_id": "cs_xyz789"
  }
}

内部 数据 载荷

{
  "type": "interaction-created",
  "interaction_id": "int_abc123def456",
  "character_session_id": "cs_xyz789"
}

字段	类型	说明
类型	string	始终 "interaction-created"
interaction_id	string	此交互会话的唯一标识符
character_session_id	string	角色会话标识符

建议操作： 存储 interaction_id 用于分析、日志记录或会话跟踪。

---

usage-limit-reached

当使用配额超出时发送。处理此消息以显示适当反馈并关闭会话。

{
  "type": "usage-limit-reached",
  "quota_type": "minutes",
  "message": "你已超出每月配额"
}

字段	类型	说明
类型	string	始终 "usage-limit-reached"
quota_type	string	超出的配额类型，例如 "minutes" 或 "api_calls"
message	string	说明该限制的人类可读消息

建议操作： 向用户显示 message 并优雅地结束会话。

---

bot-turn-completed

当机器人到达终止轮次状态时发送：它已说完、被用户打断，或因无法提供所需输出而中止。

{
  "type": "bot-turn-completed",
  "was_interrupted": false
}

字段	类型	说明
类型	string	始终 "bot-turn-completed"
was_interrupted	布尔值	true 如果用户打断了机器人； false 如果轮次正常完成
was_aborted	布尔值	可选。 true 如果轮次因无法交付所需的机器人输出而结束
error_reason	string	可选。机器可读的中止原因；目前 "audio_delivery_failed"

was_aborted 是位于 error_reason 为附加的可选字段。正常完成时会省略它们。

建议操作： 收到此消息后，更新 UI 状态并重新启用用户输入控件。

---

user-idle-warning

当用户在配置的时间内处于空闲状态时发送，提醒即将断开连接。

{
  "type": "user-idle-warning",
  "remaining_seconds": 300,
  "message": "你已空闲。你将在 5 分钟后断开连接。"
}

字段	类型	说明
类型	string	始终 "user-idle-warning"
remaining_seconds	整数	会话断开前剩余的秒数
message	字符串 | 空值	可选的人类可读警告消息

建议操作： 向用户显示警告并提示其活动，或者发送 reset-idle-timer 消息以重置空闲计时器。

---

llm-no-response

当 LLM 明确决定不响应用户输入时发送。

{
  "type": "llm-no-response",
  "reason": "abstain"
}

字段	类型	说明
类型	string	始终 "llm-no-response"
原因	字符串 | 空值	无响应的原因； "abstain" 表示模型选择不发言

建议操作： 更新你的 UI，以表明机器人选择不响应，或者根据你的 UX 要求静默处理该事件。

---

交互与转写

最终用户转写

在当前轮次中，随用户所说内容的最终转写一起发送。

{
  "type": "final-user-transcription",
  "text": "Hello, how are you today?",
  "speaker_id": "user_123",
  "speaker_name": "Alice",
  "participant_id": "participant_456"
}

字段	类型	说明
类型	string	始终 "final-user-transcription"
text	string	转写文本
speaker_id	字符串 | 空值	说话者标识符
speaker_name	字符串 | 空值	说话者显示名称
participant_id	字符串 | 空值	参与者标识符

建议操作： 显示 text 在聊天 UI 中显示，或将其追加到对话历史中。

---

moderation-response

当内容审核处理完用户输入时发送。

{
  "type": "moderation-response",
  "result": false,
  "user_input": "被标记的内容",
  "reason": "不恰当的语言"
}

字段	类型	说明
类型	string	始终 "moderation-response"
结果	布尔值	true 如果内容通过了审核； false 如果被阻止
user_input	string	已审核的输入文本
原因	字符串 | 空值	阻止原因； null 如果内容通过了审核

建议操作： 如果 结果 为 false，可选择向用户显示反馈，说明输入已被阻止。

---

behavior-tree-response

随角色 AI 行为的行为树数据一起发送。

{
  "type": "behavior-tree-response",
  "bt_code": "...",
  "bt_constants": "...",
  "narrative_section_id": "section_1"
}

字段	类型	说明
类型	string	始终 "behavior-tree-response"
bt_code	string	行为树代码
bt_constants	string	行为树的常量
narrative_section_id	string	当前叙事部分标识符

---

动作

action-response

随机器人希望执行的动作或动画的有序列表一起发送。动作仅引用在 action_config 连接时 Connect API 中的详情。 action_config.

{
  "type": "action-response",
  "actions": [
    { "name": "Move To", "target": "cube" },
    { "name": "Wave" }
  ]
}

字段	类型	说明
类型	string	始终 "action-response"
actions	对象[]	要触发的有序动作数组
actions[].name	string	动作或动画标识符
actions[].target	string	可选目标对象或角色名称

建议操作： 按顺序遍历 actions 并在你的头像或场景中触发相应的动画或行为。

---

动画与口型同步

bot-emotion

当机器人表达情绪时发送。可用于触发头像动画或更新视觉反馈元素。

{
  "type": "bot-emotion",
  "emotion": "happy",
  "scale": 2
}

字段	类型	说明
类型	string	始终 "bot-emotion"
emotion	string	情绪名称，例如 "快乐", "sad", “excited”，或 "angry"
scale	整数	强度级别： 1 = 轻微， 2 = 中等， 3 = 强烈

建议操作： 为收到的 emotion 是位于 scale.

---

visemes

在机器人说话期间频繁发送，携带用于头像口型动画的唇同步数据。值表示每种口型形状的混合权重。

{
  "type": "visemes",
  "visemes": {
    "sil": 0.0,
    "pp": 0.8,
    "ff": 0.0,
    "th": 0.0,
    "dd": 0.0,
    "kk": 0.0,
    "ch": 0.0,
    "ss": 0.0,
    "nn": 0.0,
    "rr": 0.0,
    "aa": 0.2,
    "e": 0.0,
    "ih": 0.0,
    "oh": 0.0,
    "ou": 0.0
  }
}

字段	类型	说明
类型	string	始终 "visemes"
visemes	对象	口型素键到混合权重的映射（0.0–1.0)

口型素键

键	音素
sil	静音
pp	P、B、M
ff	F、V
th	TH
dd	T、D
kk	K、G
ch	CH、J、SH
ss	S、Z
nn	N、L
rr	R
aa	A
e	E
ih	I
oh	O
ou	U、W

建议操作： 每次收到此消息时，都将 viseme 权重应用到头像口型同步的混合形状上。

---

neurosync-blendshapes

随单帧面部动画混合形状数据发送（每帧 251 个值）。

{
  "type": "neurosync-blendshapes",
  "blendshapes": [0.0, 0.1, 0.05, 0.0]
}

字段	类型	说明
类型	string	始终 "neurosync-blendshapes"
blendshapes	float[]	251 个混合形状值的数组，每个值的范围为 0.0–1.0

建议操作： 将混合形状值应用到当前帧的头像面部骨骼绑定。

---

chunked-neurosync-blendshapes

随多个帧的混合形状数据批量打包成单条消息发送。当服务器为了效率发送批量数据时，请使用此消息类型，而不要使用 neurosync-blendshapes 当服务器为了效率发送批量数据时。

{
  "type": "chunked-neurosync-blendshapes",
  "blendshapes": [
    [0.0, 0.1, 0.05],
    [0.02, 0.12, 0.04],
    [0.01, 0.09, 0.06]
  ]
}

字段	类型	说明
类型	string	始终 "chunked-neurosync-blendshapes"
blendshapes	float[][]	混合形状帧数组；每一帧包含 251 个值，范围为 0.0–1.0

建议操作： 将这些帧排队并按顺序应用，以生成平滑的面部动画。

---

blendshape-turn-stats

在机器人轮次结束时发送，包含该轮次混合形状生成的统计信息。可用于调试或分析。

{
  "type": "blendshape-turn-stats",
  "stats": {
    "total_blendshapes": 150,
    "total_audio_bytes": 48000,
    "total_turn_duration_ms": 3000.0,
    "total_audio_duration_ms": 2800.0,
    "fps": 50.0,
    "was_interrupted": false
  }
}

字段	类型	说明
类型	string	始终 "blendshape-turn-stats"
stats.total_blendshapes	整数	本轮生成的 blendshape 帧总数
stats.total_audio_bytes	整数	音频数据总大小（字节）
stats.total_turn_duration_ms	float	本轮总时长（毫秒）
stats.total_audio_duration_ms	float	音频总时长（毫秒）
stats.fps	float	blendshape 帧每秒数
stats.was_interrupted	布尔值	true 如果本轮在完成前被中断

---

音频

音频数据

当音频通过数据通道而不是（或除了）标准 WebRTC 音频轨道路由时发送。仅在以下情况下才会收到此消息： 音频路由 被设置为 "data_only" 或 "both" 在 音频配置 的 /connect 请求。

{
  "type": "audio-data",
  "sample_rate": 48000,
  "channels": 1,
  "audio": "AAEAAg==...",
  "includes_wav_header": false
}

字段	类型	说明
类型	string	始终 "audio-data"
采样率	整数	音频采样率（Hz），例如 16000, 24000，或 48000
声道数	整数	音频声道数： 1 = 单声道， 2 = 立体声
音频	string	Base64 编码的音频数据（原始 PCM 或带头部的 WAV）
包含 WAV 头部	布尔值	true 如果音频负载包含 44 字节的 WAV 头部； false 对于原始 PCM

有关完整的解码步骤、播放实现和配置选项，请参阅 通过数据通道传输音频数据.

---

相关页面

消息词汇表连接 API音频数据（通过数据通道）