跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

事件

最后更新 查看 MarkdownAgent 设置

Agent Participant 将会议活动作为 JSON 消息发送。本页介绍每种事件类型以及传送方式。

事件流动方式

会议
Agent Participant
Agent Durable Object
session.started
Alice 加入
participant.join
Alice 发言
transcript.received (partial)
transcript.received (final)
Bob 发送表情回应
broadcast.received
主持人结束会议
participant.kick_all

每条消息都具有相同的信封结构:

{ "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 个未发送事件,并在恢复时重放。
  • 不会静默丢失。 如果代理与会议断开,服务器会以 1013 upstream_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 不会重新过滤排队事件。 在旧列表下已排队的事件仍会传送。

有关关闭代码和恢复行为,请参阅重新连接。

会话事件

session.started

代理加入实时会话后发送。订阅的事件随后发送。

{
	"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 一致。

session.ended

会话结束或代理被移除时发送。服务器随后以 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.kick_all

主持人移除了所有参与者。不会为此发送 participant.leave 事件,随后会发送 session.ended。

{ "category": "message", "name": "participant.kick_all", "data": {} }

参与者事件

参与者事件按连接划分,以 peer_id 为键。同一参与者在两台设备上会产生两次加入,具有相同的 participant_id 和不同的 peer_id 值。重连会获得新的 peer_id。

participant.join

{
	"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.leave

字段与 participant.join 相同,但不含 preset_name。通过 peer_id 与加入事件匹配。

被移除时,仅设置 peer_id 和 meeting_id。其他字段为 null,waitlisted 为 false。

排除的内容

  • 代理加入时已在场的参与者。没有初始列表。
  • 代理自身的加入和离开。
  • 隐藏、录制器和直播器连接。

转录事件

transcript.received

需要在发言者的预设中启用实时转录。

{
	"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 的广播发送。

broadcast.received

{
	"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。忽略不处理的类型。

这篇文档对您有帮助吗?