For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

无

角色发出信号,表示已准备好接收消息。每次连接仅触发一次。

disconnect

断开原因 (number)

会话结束。代码为 0 当传输层未给出原因时。参见 处理错误和断开连接.

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 方法,并发出一个事件。

Emitter
事件
载荷字段

audioControls

audioStateChange

isAudioMuted, isAudioEnabled,并且在大多数更改时 audioLevel

videoControls

videoStateChange

isVideoEnabled, isVideoHidden, activeVisionSource, hasActiveVisionSource, visionSourceState

screenShareControls

screenShareStateChange

isScreenShareActive,以及在启用、禁用和重置时 isScreenShareEnabled

相关参考

ConvaiClient 参考配置和类型参考处理错误和断开连接

最后更新于

这有帮助吗?