Web SDK 事件参考
Convai Web SDK 客户端及其媒体控制发出的每个事件的参考,包括每个事件携带的负载以及触发时间。
ConvaiClient 通过……发出本页上的事件 on(event, callback),它会返回一个取消订阅函数,并且 off(event, callback)。该 useConvaiClient 中的钩子 @convai/web-sdk/react 暴露相同的 开启 和 off。事件名称是普通字符串,载荷不由发出器进行类型标注,因此请用导出的类型为回调参数加注解。
const unsubscribe = client.on('botReady', () => {
client.sendUserTextMessage('你好');
});
unsubscribe();连接事件
connect
无
connect() 或 connectWithPublicationGrant() 已打开传输层。角色仍可能尚未就绪;请等待 botReady 后再发送。
botReady
无
角色发出信号,表示已准备好接收消息。每次连接仅触发一次。
error
未知
connect() 或 connectWithPublicationGrant() 失败(同一错误会被重新抛出),或者在 LiveKit 传输层上,45 秒内未收到就绪信号(在 45000 毫秒内未收到 bot-ready).
stateChange
Convai 客户端状态
的任意字段 client.state 发生变化。
interactionCreated
交互已创建: { interactionId: string; characterSessionId: string }
Convai 会为该会话分配一个交互 ID。
botAudioTrack
MediaStreamTrack
WebSocket 会话会暴露一个角色音轨。当前的 Pipecat WebSocket 传输不会触发该事件,因为它自己播放语音,并且不暴露角色音轨。参见 使用 WebSocket 传输.
对话事件
conversationStart
{ sessionId: number; userMessage: string; timestamp: number }
新一轮开始。 sessionId 每轮递增,并与 client.conversationSessionId. 时间戳 是一个 Date.now() 值。
turnEnd
{ sessionId: number; duration: number; timestamp: number }
角色在至少一轮开始后停止说话。 duration 是与之匹配的……以来的秒数 conversationStart.
消息
聊天消息
消息列表发生变化。载荷是列表中的最后一条消息,因此当流式消息增长时会再次触发。
messagesChange
ChatMessage[]
消息列表发生变化,包括流式更新和重置。
userTranscriptionChange
字符串
最终用户语音的实时转写发生变化。空字符串会将其清除。
llmNoResponse
无
角色故意不回答这一轮。
指标
Record<string, unknown>
Convai 发送一条指标消息。原始数据也会附加到 client.state.metrics.
conversationStart.userMessage 标识了这一轮的起因:
已裁剪的消息文本
sendUserTextMessage()
[语音]
最终用户开始说话
[trigger:<name>]
sendTriggerMessage(); <name> 当未传入触发器名称时为空
[context-update:<mode>]
updateContext() 与 run_llm: "true",或配合 respond_mode: "must_respond" 并且没有 run_llm; <mode> 默认为 追加
[vision-trigger:must_respond]
visionTrigger() 与 respondMode: "must_respond"
[scene-metadata:must_respond]
updateSceneMetadata() 与 respondMode: "must_respond"
语音事件
speakingChange
布尔值
角色开始(true)或停止(false)说话。重置或中断也会触发 false.
botOutput
{ text: string; spoken: boolean; aggregatedBy: string; segmentId?: number | string; spokenStatus?: string }
Convai 发送一个聚合输出片段。 aggregatedBy is "sentence" 当 Convai 未指定它时。同一个 segmentId 可能会随着语音推进而重复。
botTtsText
{ text: string }
Convai 会在文本被说出时发送它。
botTtsStarted
无
响应的语音合成开始。
botTtsStopped
无
响应的语音合成停止。
userMuteStarted
无
Convai 报告已停止接收最终用户的音频。
userMuteStopped
无
Convai 报告再次开始接收最终用户的音频。
emotionChange
{ emotion: string; scale?: number } | null
角色的情绪发生变化。 null 在重置和断开连接时。需要 enableEmotion: true。参见 使用角色情绪.
口型同步事件
这些需要 enableLipsync: true。请从 client.blendshapeQueue 读取帧,而不是从这些载荷中读取。参见 使用 blendshape 驱动面部动画.
blendshapes
来自 Convai 的原始 chunk 对象,包含一个 blendshapes 帧数组
接受当前响应的一个 blendshape chunk。
blendshapeStatsReceived
来自 Convai 的原始对象,转轮统计信息位于 stats
Convai 发送轮末 blendshape 统计信息,表示该响应不会再有更多帧。
blendshapeCancel
来自 Convai 的原始取消对象
Convai 取消响应的 blendshape 流,例如在中断之后。
动作事件
actionResponse
动作响应事件: { actions: Array<ConvaiAction | ConvaiToolCall> }
Convai 会为一轮发送动作。空数组表示没有动作。在选择模型输出版本 2 时不会发出。
modelOutput
模型输出消息
当会话选择了 capabilities.modelOutputVersion: 2时,会收到一个有效的模型输出信封。重复的 output_id 会被丢弃。
modelOutputProtocolError
模型输出协议错误: { code: "invalid_model_output"; message: string }
版本 2 的会话上的模型输出信封格式错误或不受支持。
参见 处理角色动作 了解如何使用这些事件。
确认和会话事件
serverResponse
服务器响应: { event_type: string; status: "success" | "error" | "processing" | "pending"; message: string | null; extras: ServerResponseExtras | null }
Convai 确认客户端发送的消息。 事件类型 是该消息的类型,例如 上下文更新 或 action-result.
idleWarning
{ remainingSeconds: number | null }
Convai 警告将关闭不活动的会话。调用 resetIdleTimer() 可保持打开。
媒体控制事件
client.audioControls, client.videoControls,以及 client.screenShareControls 各自都有自己的 开启 和 off 方法,并发出一个事件。
audioControls
audioStateChange
isAudioMuted, isAudioEnabled,并且在大多数更改时 audioLevel
videoControls
videoStateChange
isVideoEnabled, isVideoHidden, activeVisionSource, hasActiveVisionSource, visionSourceState
screenShareControls
screenShareStateChange
isScreenShareActive,以及在启用、禁用和重置时 isScreenShareEnabled
相关参考
ConvaiClient 参考配置和类型参考处理错误和断开连接最后更新于
这有帮助吗?