Agent Participant 将会议活动作为 JSON 消息发送。本页介绍每种事件类型以及传送方式。
每条消息都具有相同的信封结构:
{ "category": "message", "name": "<event name>", "data": {} }根据 name 分派。忽略未知字段和事件名称。除应用定义的广播有效负载外,字段均采用 snake_case。
始终发送会话事件。其他事件需要在 subscriptions 查询参数中包含相应类别。
| 类别 | 事件 |
|---|---|
| 始终发送 | session.started, session.ended, participant.kick_all |
participant |
participant.join, participant.leave |
transcript |
transcript.received |
broadcast |
broadcast.received |
传递类别,而不是事件名称:?subscriptions=transcript,participant。未知类别会导致连接被拒绝,并返回 400 INVALID_QUERY。
- 仅实时。 没有历史记录或快照。会话中途打开的连接只接收后续事件。
- 按来源排序。 转录按顺序到达,参与者事件也按顺序到达。不同来源之间没有顺序保证。
- 服务器重启时至少一次。 如果服务器在发送过程中重启,同一事件可能到达两次。
- 重连期间排队。 每个连接最多保留 10,000 个未发送事件,并在恢复时重放。
- 不会静默丢失。 如果代理与会议断开,服务器会以
1013upstream_lost关闭。重新加入后,第二个session.started表示出现了间断。
要在 WebSocket 断开后继续接收事件,请在连接后发送 connection.get 请求,并存储返回的 connection.id。重新连接时,将其作为 connection_id 查询参数传递。
只有后端与 Agent WebSocket 之间的 WebSocket 意外断开时才能恢复,例如发生网络错误,或使用 1000 以外的代码突然关闭。如果后端使用 1000 正常关闭 WebSocket,代理会立即离开会议,没有可恢复的内容。
你接收的内容取决于离开时长:
| 情况 | 接收的内容 |
|---|---|
| 在 5 秒宽限期内恢复 | 先按原始顺序接收排队事件,再接收实时事件。不会丢失任何内容。 |
| 代理离开会议后恢复 | 先接收新的 session.started,再接收实时事件。代理离开期间的事件会丢失。 |
以 queue_overflow 关闭 |
没有可恢复的内容。排队事件超过 10,000 个。请在不带 connection_id 的情况下重新连接。 |
在 session.ended 后以 session_ended 关闭 |
没有可恢复的内容。为下一会话打开新连接。 |
处理事件时:
- 将第二个
session.started视为间断。 间断期间的加入、离开和转录不会重放,因此参与者列表可能已过期。 - 使处理程序具有幂等性。 如果服务器在发送事件时重启,同一事件可能到达两次。
- 恢复时更改
subscriptions不会重新过滤排队事件。 在旧列表下已排队的事件仍会传送。
有关关闭代码和恢复行为,请参阅重新连接。
代理加入实时会话后发送。订阅的事件随后发送。
{
"category": "message",
"name": "session.started",
"data": {
"session": {
"id": "ses_1",
"meeting_id": "mtg_1",
"started_at": "2026-09-23T10:00:00.000Z",
"ended_at": null
}
}
}session.id 与会话 REST API 和 webhook 一致。
会话结束或代理被移除时发送。服务器随后以 1000 session_ended 关闭。要跟踪下一个会话,请打开新连接。
{
"category": "message",
"name": "session.ended",
"data": {
"session": {
"id": "ses_1",
"meeting_id": "mtg_1",
"started_at": "2026-09-23T10:00:00.000Z",
"ended_at": "2026-09-23T10:45:12.000Z"
},
"reason": "host_ended_meeting"
}
}reason |
含义 |
|---|---|
all_participants_left |
最后一名参与者离开且关闭超时已过 |
host_ended_meeting |
主持人为所有人结束会议 |
force_cleanup |
平台关闭孤立会话 |
将未知原因视为 all_participants_left。在 session.ended 后可能遗漏延迟到达的最终转录。
已连接的代理会计为参与者,因此代理连接期间,会话不会自行结束。请参阅计费和结束会话。
主持人移除了所有参与者。不会为此发送 participant.leave 事件,随后会发送 session.ended。
{ "category": "message", "name": "participant.kick_all", "data": {} }参与者事件按连接划分,以 peer_id 为键。同一参与者在两台设备上会产生两次加入,具有相同的 participant_id 和不同的 peer_id 值。重连会获得新的 peer_id。
{
"category": "message",
"name": "participant.join",
"data": {
"participant": {
"peer_id": "peer_7f3a",
"participant_id": "par_1",
"meeting_id": "mtg_1",
"custom_participant_id": "customer-user-1",
"display_name": "Alice",
"picture_url": null,
"preset_id": "pst_1",
"preset_name": "group_call_host",
"waitlisted": false
}
}
}| 字段 | 说明 |
|---|---|
peer_id |
此连接 |
participant_id |
参与者 ID,与 REST API 中相同 |
custom_participant_id |
你为参与者设置的 ID,或 null |
display_name |
显示名称 |
picture_url |
显示图片 URL,或 null |
preset_id |
预设 ID,或 null |
preset_name |
预设名称,或 null |
waitlisted |
连接等待主持人批准时为 true |
字段与 participant.join 相同,但不含 preset_name。通过 peer_id 与加入事件匹配。
被移除时,仅设置 peer_id 和 meeting_id。其他字段为 null,waitlisted 为 false。
- 代理加入时已在场的参与者。没有初始列表。
- 代理自身的加入和离开。
- 隐藏、录制器和直播器连接。
需要在发言者的预设中启用实时转录。
{
"category": "message",
"name": "transcript.received",
"data": {
"text": "Hello everyone.",
"is_final": true,
"started_at": "2026-09-23T10:00:03.000Z",
"ended_at": "2026-09-23T10:00:05.000Z",
"confidence": 0.94,
"speaker": {
"peer_id": "peer_7f3a",
"participant_id": "par_1",
"custom_participant_id": "customer-user-1",
"display_name": "Alice"
}
}
}| 字段 | 说明 |
|---|---|
text |
转录的文本 |
is_final |
结果为最终结果时为 true。这并不表示发言者的发言轮次已结束。 |
started_at |
服务器接收转录的时间,精确到秒。不是语音开始时间。 |
ended_at |
语音结束时间,精确到秒 |
confidence |
语音转文本置信度,范围为 0 到 1 |
speaker |
发言连接。peer_id 与 participant.join 匹配。 |
同一段语音的部分结果 (is_final: false) 后可能跟随最终结果。没有片段 ID。请替换每位发言者的最新部分结果,并只存储最终结果。
广播是参与者发送到会议的自定义消息。应用发送的任何 type 和 payload 都会到达代理,因此广播可用于向代理提供应用专用信号。
使用广播 API 从任何参与者发送广播:
await meeting.participants.broadcastMessage("my-broadcast", {
message: "Greetings!",
peerId: meeting.self.peerId,
});回应已经以这种方式工作。Reactions Manager 插件将每个回应作为类型为 reactions 的广播发送。
{
"category": "message",
"name": "broadcast.received",
"data": {
"type": "reaction",
"payload": { "emoji": "🔥", "peerId": "peer_7f3a" },
"created_at": "2026-09-23T10:03:10.123Z"
}
}| 字段 | 说明 |
|---|---|
type |
应用定义的类型,例如 reactions |
payload |
应用定义的 JSON 对象,按发送时的内容转发 |
created_at |
广播发送时间 |
- 按
type过滤。对于回应,payload.reaction是表情符号,空字符串会清除回应。 payload键按发送时的内容转发,因此会保留应用的大小写形式,例如peerId。- 发件人未经验证。不要信任
payload中用于授权的身份字段。 - SDK 还会发送内部类型,例如
spotlight。忽略不处理的类型。