客户端频道会话
本页接口使用当前 IM 登录的 User Token。App Token、频道票据、媒体 Token 不能代替它。频道操作使用 HTTP，不要求先连接 IM WebSocket。推荐由客户端 SDK封装媒体和生命周期。
加入频道
/client/v1/rtc/channels/{channel_id}/join路径参数
channel_id 见频道管理。应用和用户名由 User Token 确定，不接受客户端自行指定。
请求体
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
client_session_id | String | 是 | 1～64 个可打印 ASCII 字符，不含空格；同一次加入的重试保持不变 |
ticket | String | ticket 频道必填 | 业务服务端交付给本人的一次性票据；open 频道不传 |
请求示例
示例变量 $USER_TOKEN 为当前用户登录令牌，$RTC_TICKET 为业务服务端交付的票据：
curl -X POST "$IM_API/client/v1/rtc/channels/meeting-demo/join" \
-H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" \
-d "{\"client_session_id\":\"join-meeting-demo-001\",\"ticket\":\"$RTC_TICKET\"}"响应
首次成功 201，同键重放 200；返回 channel、session、media、heartbeat_interval_seconds。拿到媒体凭据只代表会话已预留，通常还处于 joining：必须连接媒体并等服务端确认 joined，才能认为加入完成。
房间准备中为 503 unavailable/media_preparing，带 Retry-After；details 可包含本人 session_id 和 join_deadline。持有 session ID 后按原会话续凭据；否则保持原键和票据重试。准备、媒体连接和入会确认共用首次 60 秒期限，不重置期限。取消或失败时立即停止采集并提交退出。
错误
| HTTP / code | details.reason | 处理 |
|---|---|---|
404 / not_found | channel_not_found | 不存在或缺少有效票据；不区分以防泄露 |
403 / permission_denied | channel_banned、rtc_disabled 等 | 修正授权 / 配置，不能自动重新占位 |
409 / conflict | media_resource_busy、joined_on_other_device | 用户正占用通话 / 频道，或另一设备占用 |
409 / conflict | session_already_exists、idempotency_conflict | 查当前会话，恢复原请求；不能随机换键 |
409 / conflict | channel_closed、session_left、join_deadline_exceeded | 停止本次加入并清理 |
409 / limit_exceeded | channel_full、active_media_limit | 等待席位 / 额度释放 |
503 / unavailable | media_preparing、media_reclaiming、media_unavailable、admission_unavailable | 有界重试，保持原加入键并遵循期限 |
其余参数、认证和限流规则见错误码。
查询本人当前会话
/client/v1/rtc/channel-session/current请求示例
curl "$IM_API/client/v1/rtc/channel-session/current" -H "Authorization: Bearer $USER_TOKEN"响应
200：session 为本登录会话的频道会话，无记录时为 null。用于请求结果未知时恢复定位；不能拿另一登录会话的 session 操作。
错误
认证失效按通用错误处理。
查询频道
/client/v1/rtc/channels/{channel_id}路径参数
channel_id 同加入接口。
请求示例
curl "$IM_API/client/v1/rtc/channels/meeting-demo" -H "Authorization: Bearer $USER_TOKEN"响应
200 和 channel，没有管理处置说明。未被频道封禁的本应用用户可查看 open 频道；ticket 频道需要本登录对应的 joining / joined 会话。仅持有尚未消费的票据不能调用此查询。
错误
无权查看受控频道按 404 not_found 处理。
查询频道成员
/client/v1/rtc/channels/{channel_id}/sessions路径参数
channel_id 同加入接口。
查询参数
使用 cursor、limit，不接受 status。本人须有本登录对应的 joining / joined 会话才能查询成员。
请求示例
curl "$IM_API/client/v1/rtc/channels/meeting-demo/sessions?limit=20" -H "Authorization: Bearer $USER_TOKEN"响应
200：items、next_cursor、members_version、media_observed_at。仅包含 joining / joined 的成员投影，不能据此推断全部占位已释放。
错误
无成员权限按 404 not_found 处理。分页中成员版本变化为 409 version_conflict/members_changed，需从第一页重新拉取，不能拼接不同版本名单。
查询本人会话
/client/v1/rtc/channels/{channel_id}/sessions/{session_id}路径参数
session_id 为服务器返回的字符串 ID，不转浮点数或截断。
请求示例
curl "$IM_API/client/v1/rtc/channels/meeting-demo/sessions/$RTC_SESSION_ID" -H "Authorization: Bearer $USER_TOKEN"响应
200：session。用来确认 joining 是否已成为 joined，或退出是否完成。
错误
不是本登录会话的资源按 404 not_found/session_not_found 处理。
续发媒体凭据
/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/token路径参数与请求体
路径参数同本人会话查询；请求体为空对象或省略。只允许本人有效的 joining / joined 会话，不重新消费票据或预留席位。
请求示例
curl -X POST "$IM_API/client/v1/rtc/channels/meeting-demo/sessions/$RTC_SESSION_ID/token" \
-H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" -d '{}'响应
200：session、media。凭据通常为 60 秒，joining 不超过原加入期限，joined 不超过会话最长期限。LiveKit 自身的连接刷新不替代本接口的业务授权检查。
错误
关闭、超时、已退出、封禁或登录吊销不再续发；准备中返回 503。不要将拒绝处理成自动重新加入。
心跳
/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/heartbeat路径参数与请求体
同续凭据接口；空请求体。不提交 media_connected，服务端根据实际媒体观察确认连接。
请求示例
curl -X POST "$IM_API/client/v1/rtc/channels/meeting-demo/sessions/$RTC_SESSION_ID/heartbeat" \
-H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" -d '{}'响应
200：session、channel_status、channel_version、members_version、server_time。服务端建议间隔 15 秒；当前 SDK 约 10 秒发送一次。joined 会话 45 秒没有有效心跳开始退出，最长参与 12 小时。心跳不延长 joining 期限，不使已超时会话复活。
错误
认证、授权及会话错误同上述接口。收到 leaving / left 或频道终态立即停止媒体；版本变化时刷新频道 / 成员。
退出
/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/leave路径参数与请求体
同续凭据接口；空请求体。
请求示例
curl -X POST "$IM_API/client/v1/rtc/channels/meeting-demo/sessions/$RTC_SESSION_ID/leave" \
-H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" -d '{}'响应
返回 session，清理中为 202 / leaving，已完成为 200 / left。可重复退出。客户端即使 HTTP 失败也先断开媒体、停止采集；服务端回收继续执行，新加入可能暂时仍忙线。
错误
非本人登录会话返回 404 not_found；登录失效按认证错误处理，不应切换为新用户提交旧会话操作。
数据结构
| 对象 | 字段与含义 |
|---|---|
| Session | session_id、channel_id、username、role、status、version；reserved_at、join_deadline、max_expires_at、joined_at、leaving_at、left_at；leave_reason、media_connected、media_observed_at；本人响应另有 client_session_id |
| Participant | session_id、username、role、status、joined_at、version、media_connected、media_observed_at、media_identity；不含设备或登录会话信息 |
| MediaCredential | provider=livekit、url、room、identity、token、expires_at；只交付本人会话 |
时间遵循通用格式，尚未发生的时间为 null；media_connected 可为 true、false、null，null 表示观察未知。media_identity 用于精确绑定轨道和已授权成员，不是用户名，不授予入会权。票据和媒体 Token 不持久保存；所有这些响应带 Cache-Control: no-store。