在用户可以通过 RealtimeKit SDK 加入会议之前,您的后端必须使用 Add Participant API 将该用户作为参与者添加到该会议中。 在 RealtimeKit 中,参与者(participant) 代表被允许加入特定会议的用户。
您可以把这想象成学生注册进课堂。会议就是课堂,而添加参与者就是您注册用户以允许他们出席的方式。
当您添加参与者时,您还需要选择应用哪个预设(preset)。预设定义了该参与者的角色、权限和会议体验。
当您使用 Add Participant API 端点将参与者添加到会议时,它会返回:
- 标识该参与者在会议中的参与者
id。 - 该参与者的身份验证令牌
token。
您的后端应该将其提供给您的前端应用程序。当用户选择加入会议时,前端将该令牌传递给 RealtimeKit SDK。
RealtimeKit 使用令牌对参与者进行身份验证,并确定哪个会议和哪个参与者正在加入。如果没有有效的身份验证令牌,SDK 就无法代表该参与者加入会议。只要参与者拥有有效的身份验证令牌,该参与者就可以随着时间的推移加入同一会议的多个活动会话期(session)。
参与者身份验证令牌是 JSON Web Token(JWT)。meetingId 和 participantId 字段将每个令牌限定为一次会议中的一名参与者。
默认情况下,令牌签发后立即生效,并在 100 天后过期。如需设置自定义有效期,请在添加参与者时于 token 对象中传入 not_before 和 expires_on,或在刷新令牌时于请求正文中传入。两个字段都是可选的 RFC 3339 时间戳,需带时区偏移,例如 2026-10-01T09:00:00Z(UTC)或 2026-10-01T14:30:00+05:30:
not_before默认为当前时间,也可以设为过去的时间。expires_on默认为not_before之后 100 天,并且必须是未来时间。- 有效期不得超过 100 天。
响应会以 UTC 返回已签发令牌的 not_before 和 expires_on 值。
你的后端可以在令牌过期之前或之后调用 Refresh Participant Token 端点。新令牌沿用现有参与者记录,包括其参与者 id 和预设。刷新不会使先前签发的令牌失效。每个令牌在其自身过期时间之前都保持有效。
如需撤销单个令牌,请向 /accounts/{account_id}/realtime/kit/{app_id}/meetings/{meeting_id}/participants/{participant_id}/token 发送 DELETE 请求,并在请求正文中传入令牌:
{
"token": "<PARTICIPANT_AUTH_TOKEN>"
}该参与者的其他令牌仍然有效。
令牌被撤销后,所有位置最多可能需要 60 秒才会拒绝该令牌。在此期间,参与者可能仍可使用被撤销的令牌重新加入会议。如需立即阻止所有参与者令牌的访问,请改为删除参与者。
如需撤销参与者在某场会议中的所有令牌,请调用删除参与者端点。
撤销令牌或删除参与者,也会将其从会议的活动会话中移除(如果存在活动会话)。
参与者无法使用已过期、尚未生效或已撤销的令牌加入会议。RealtimeKit UI 和 Core SDK 会将该令牌报告为无效。RealtimeKit 会在参与者进入会议舞台之前将其拒绝,因此不会计费。API 错误响应会包含 reason 字段,其值可能是 participant_token_expired、participant_token_not_yet_valid、participant_token_revoked 或 participant_token_invalid。
在添加参与者时,您还可以选择提供一个自定义参与者标识符,称为 custom_participant_id。此值完全由您使用。
RealtimeKit 会存储它并在 API 中返回,但不会使用它来控制访问。它允许您将应用程序的用户映射到 RealtimeKit 参与者,并将 RealtimeKit 会话数据、事件或分析与您系统中的用户信息相关联。
在理解参与者后,您可以探索以下主题:
- 了解预设(Presets)如何为参与者定义角色和权限
- 开始使用 RealtimeKit SDK