读取原始传输消息
使用带类型的 rawMessage 事件观察会话通过任意传输接收的每条消息,包括 MCP 工具生命周期帧和未知类型。
观察 Convai 会话收到的消息,这些消息是在从线路中解码并且在 SDK 解释之前得到的。使用 rawMessage event 来记录流量、读取 MCP 工具生命周期帧,或处理 SDK 不会转换为自身事件的消息类型。它在 LiveKit、WebSocket 和 SSE 上的工作方式相同。
前提条件
已安装 Convai Web SDK,并且有可连接的客户端。参见 Web SDK 快速入门.
订阅原始消息
调用 client.on('rawMessage', listener)。它会返回一个取消订阅函数。React Hook 通过其 开启 和 off 方法暴露相同的监听器。
import { useEffect } from 'react';
import { useConvaiClient } from '@convai/web-sdk/react';
import { ConvaiWidget } from '@convai/web-widget/react';
const config = {
apiKey: 'YOUR_API_KEY',
characterId: 'YOUR_CHARACTER_ID',
startWithAudioOn: false,
};
export default function Chat() {
const client = useConvaiClient(config);
useEffect(() => client.on('rawMessage', (event) => {
console.log(event.transport, event.message);
if (event.transport === 'sse') console.log(event.request.logicalTurnIds);
}), [client.on]);
return <ConvaiWidget convaiClient={client} />;
}如上所示,从 effect 中返回取消订阅函数,这样卸载和重新渲染时就会移除监听器。
你也可以使用以下方式移除监听器: client.off('rawMessage', listener),并传入相同的函数引用。
订阅不会建立连接或发送任何内容。小部件,或你自己调用 connect(),负责控制连接。监听器只覆盖传入消息;它不会发布事件,也不会观察传出流量。
读取事件载荷
每个事件都携带 消息, byteLength 和 transport。其余字段取决于传输方式,因此请先检查 event.transport ,TypeScript 会为你缩小类型。
传输
消息
额外字段
'livekit'
解码后的 JSON 封装,其中包括嵌套的 server-message 数据。非 JSON 数据包不会被发出。
participant:由房间提供的发送者。它可能不存在。
'websocket'
解码后的 JSON 封装,其中包括嵌套的 server-message 数据。非 JSON 数据包不会被发出。
无
'sse'
{ type: eventName, data: decodedData }。不是 JSON 的数据会保持为字符串。
request:发起请求的 logicalTurnIds 和 messageTypes.
消息is未知。在使用前请验证其结构。消息而且 SSE 请求元数据与 SDK 自身的处理是分离的。请将它们视为只读。byteLength是传入载荷大小。对于 SSE,它统计合并后的 data 字段,不包括事件帧包装。在 SSE 中,会包含 session、done、error 和 unknown 帧。SSE 注释以及没有 data 的帧不包含在内。
SSE 会先报告单独的文本帧,然后 SDK 才将它们批处理为聊天消息。
检查消息来自哪里
在 LiveKit 上,使用以下方式验证发送者: event.participant 并与当前房间进行比对。它是原始的 participant 对象,不是副本。
在 SSE 上,使用 event.request.logicalTurnIds 将帧匹配到导致它的用户轮次。仅控制请求可以是空列表。当请求被中断时,其剩余帧不会被发出。
读取 MCP 工具生命周期帧
关于工具调用的消息,包括 MCP 工具,会像 rawMessage 其他帧一样到达,同时还有 SDK 不会解释的事件类型。读取 类型 字段于 消息 来筛选出你需要的项,例如 llm-function-call-in-progress 和 llm-function-call-stopped,或者一个 server-message 其 data.type is mcp-tool-heartbeat.
何时使用 rawMessage
对于它们已经涵盖的内容,请使用 SDK 的常规事件,这些事件列在 Web SDK 事件参考中,适用于它们已覆盖的任何内容。请使用 rawMessage 用于它们未覆盖的内容:调试和记录流量、工具和 MCP 生命周期帧、SDK 不解释的服务器消息类型,以及 SSE 上的按请求关联。
在你的监听器中抛出的异常不会阻止 SDK 正常处理该消息。
API 参考
client.on('rawMessage', listener)
(listener: (event: RawMessageEvent) => void) => () => void
订阅传入消息。返回一个取消订阅函数。
client.off('rawMessage', listener)
void
通过引用移除同一个监听器。
RawMessageEvent
联合类型
事件载荷。通过以下方式缩小其类型: transport.
event.message
未知
在 SDK 解释之前解码的线路消息。使用前请验证其结构。
event.byteLength
number
传入载荷大小。对于 SSE,是不含事件帧包装的合并 data 字段。
event.transport
'livekit' | 'websocket' | 'sse'
传递该消息的传输方式。
event.participant
未知
仅限 LiveKit。由房间提供的发送者;可能不存在。
event.request
SSERequestContext
仅限 SSE。发起请求的 logicalTurnIds 和 messageTypes.
SSERequestContext
{ transport: 'sse'; logicalTurnIds: string[]; messageTypes: string[] }
产生该事件的 SSE 请求标识。
最后更新于
这有帮助吗?