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

读取原始传输消息

使用带类型的 rawMessage 事件观察会话通过任意传输接收的每条消息,包括 MCP 工具生命周期帧和未知类型。

观察 Convai 会话收到的消息,这些消息是在从线路中解码并且在 SDK 解释之前得到的。使用 rawMessage event 来记录流量、读取 MCP 工具生命周期帧,或处理 SDK 不会转换为自身事件的消息类型。它在 LiveKit、WebSocket 和 SSE 上的工作方式相同。

前提条件

订阅原始消息

调用 client.on('rawMessage', listener)。它会返回一个取消订阅函数。React Hook 通过其 开启 和 off 方法暴露相同的监听器。

src/Chat.tsx
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 请求标识。

最后更新于

这有帮助吗?