客戶端頻道會話

本頁是客戶端加入、保持和退出頻道的 HTTP 介面。客戶端 SDK 已經封裝了這些介面以及媒體連線，一般直接用 SDK；只有自己實現客戶端時才需要本頁。

這些介面用使用者當前登入 IM 的 User Token 呼叫，App Token、頻道票據和媒體 Token 都不能代替。它們是普通的 HTTP 請求，不需要先連上 IM 的 WebSocket。

一次完整的參會過程：

步驟	介面	說明
1	加入頻道	返回會話 `session` 和媒體憑據 `media`，會話狀態為 `joining`
2	用 `media` 連線媒體服務	服務端觀察到連線後，會話變為 `joined`，這時才算真正入會
3	每隔約 10 到 15 秒呼叫心跳	45 秒沒有心跳會被請出頻道
4	媒體憑據快到期時續發媒體憑據	憑據通常 60 秒有效
5	離開時退出	先斷開媒體、停止採集，再呼叫退出

不確定上一次請求的結果時（如網路中斷），用查詢本人當前會話找回自己的會話，繼續用它，不要另起一次加入。

加入頻道

POST/client/v1/rtc/channels/{channel_id}/join

路徑引數

引數	型別	說明
`channel_id`	String	頻道 ID，見頻道管理

應用和使用者由 User Token 確定，不能在請求中指定。

請求體

欄位	型別	必填	說明
`client_session_id`	String	是	客戶端為這次加入生成的 ID，1 到 64 個可列印 ASCII 字元，不能有空格。重試同一次加入時保持不變
`ticket`	String	`ticket` 頻道必填	你的服務端發給本人的票據；`open` 頻道不要傳

請求示例

$USER_TOKEN 為當前使用者的登入令牌，$RTC_TICKET 為服務端交給他的票據：

bash

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 Created，用同一個 client_session_id 重試返回 200 OK。響應體包括：

欄位	說明
`channel`	頻道物件
`session`	本人的會話，通常為 `joining`
`media`	媒體憑據，用來連線媒體服務
`heartbeat_interval_seconds`	服務端建議的心跳間隔

拿到媒體憑據只表示席位已經為你保留：要用它連上媒體服務，等會話變為 joined，才算加入完成。

媒體房間還在準備時，返回 503 unavailable，details.reason 為 media_preparing，帶 Retry-After；details 中可能有本人的 session_id 和截止時間 join_deadline：

有 session_id 時，按續發媒體憑據繼續這個會話；
沒有時，用同一個 client_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`	已有會話，或同一個 `client_session_id` 用於不同的請求。查詢當前會話後繼續原來的那次加入，不要換一個新 ID
409	`conflict`	`channel_closed`、`session_left`、`join_deadline_exceeded`	頻道已關閉、會話已退出或超過了 60 秒期限。停止這次加入並清理
409	`limit_exceeded`	`channel_full`、`active_media_limit`	頻道已滿或應用的併發額度已滿，等有空位後再試
503	`unavailable`	`media_preparing`、`media_reclaiming`、`media_unavailable`、`admission_unavailable`	暫時不可用。用同一個 `client_session_id` 有限次地重試，不超過加入期限

引數、認證和限流等其他錯誤見錯誤碼。

查詢本人當前會話

查詢本次登入在頻道中的會話，用於請求結果不確定時找回會話。只能看到本次登入（這臺裝置）的會話。

GET/client/v1/rtc/channel-session/current

請求示例

bash

curl "$IM_API/client/v1/rtc/channel-session/current" -H "Authorization: Bearer $USER_TOKEN"

響應

成功返回 200 OK，session 為本次登入的會話，沒有時為 null。

錯誤

登入失效等通用錯誤見錯誤碼。

查詢頻道

GET/client/v1/rtc/channels/{channel_id}

路徑引數

channel_id 同加入頻道。

請求示例

bash

curl "$IM_API/client/v1/rtc/channels/meeting-demo" -H "Authorization: Bearer $USER_TOKEN"

響應

成功返回 200 OK 和 channel，不含關閉說明等管理資訊。

誰能查詢：open 頻道，沒有被這個頻道封禁的本應用使用者都能查詢；ticket 頻道，只有本次登入在頻道中有 joining 或 joined 會話的使用者能查詢，只拿到票據、還沒加入的不行。

錯誤

沒有許可權查詢時返回 404 not_found，與頻道不存在相同。

查詢頻道成員

查詢頻道中正在加入和已加入的成員。只有本次登入在頻道中有 joining 或 joined 會話時才能查詢。

GET/client/v1/rtc/channels/{channel_id}/sessions

路徑引數

channel_id 同加入頻道。

查詢引數

引數	型別	必填	說明
`limit`	Number	否	每頁的條數，見分頁
`cursor`	String	否	上一頁返回的 `next_cursor`

不支援 status。

請求示例

bash

curl "$IM_API/client/v1/rtc/channels/meeting-demo/sessions?limit=20" -H "Authorization: Bearer $USER_TOKEN"

響應

成功返回 200 OK：

欄位	說明
`items`	成員的陣列，只含 `joining`、`joined` 的成員。退出中的成員不在其中，但可能還佔著席位
`next_cursor`	下一頁的遊標，最後一頁為 `null`
`members_version`	成員列表的版本號
`media_observed_at`	最近一次確認媒體狀態的時間

錯誤

HTTP 狀態碼	`code`	說明
404	`not_found`	沒有查詢成員的許可權
409	`version_conflict`	`details.reason` 為 `members_changed`：翻頁期間成員變了。從第一頁重新查詢，不要把不同版本的結果拼在一起

查詢本人會話

查詢本人的某個會話，用於確認 joining 是否已變為 joined，或退出是否已完成。

GET/client/v1/rtc/channels/{channel_id}/sessions/{session_id}

路徑引數

引數	型別	說明
`channel_id`	String	頻道 ID
`session_id`	String	加入時返回的會話 ID。按字串儲存，不要轉成數字或截斷

請求示例

bash

curl "$IM_API/client/v1/rtc/channels/meeting-demo/sessions/$RTC_SESSION_ID" -H "Authorization: Bearer $USER_TOKEN"

響應

成功返回 200 OK 和 session。

錯誤

不是本次登入的會話時返回 404 not_found，details.reason 為 session_not_found。

續發媒體憑據

為本人還在 joining 或 joined 的會話換一份新的媒體憑據。不會再次使用票據或佔用新的席位。

POST/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/token

路徑引數與請求體

路徑引數同查詢本人會話。請求體為空物件，或者不傳。

請求示例

bash

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 OK，包括 session 和新的 media。憑據通常 60 秒有效：joining 的會話不超過加入期限，joined 的會話不超過會話的最長時長。LiveKit 自己的連線重新整理不能代替這個介面，服務端在這裡重新檢查許可權。

錯誤

頻道已關閉、加入超時、會話已退出、使用者被封禁或登入被吊銷時，不再續發；媒體房間準備中返回 503。被拒絕後不要自動重新加入。

心跳

告訴服務端客戶端還在。是否真的連著媒體由服務端自己觀察，不需要客戶端上報。

POST/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/heartbeat

路徑引數與請求體

同續發媒體憑據，請求體為空。

請求示例

bash

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 OK：session、頻道狀態 channel_status、頻道版本 channel_version、成員版本 members_version 和服務端時間 server_time。

規則	值
服務端建議的間隔	15 秒；當前 SDK 約每 10 秒一次
多久沒有心跳會被請出	`joined` 的會話 45 秒
最長參會時長	12 小時

心跳不會延長 60 秒的加入期限，也不能讓已經超時的會話恢復。

錯誤

認證、許可權和會話的錯誤同上面的介面。

響應中會話變為 leaving 或 left，或頻道已關閉：立即停止媒體。
channel_version 或 members_version 變了：重新查詢頻道或成員。

退出

POST/client/v1/rtc/channels/{channel_id}/sessions/{session_id}/leave

路徑引數與請求體

同續發媒體憑據，請求體為空。

請求示例

bash

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 Accepted、狀態 leaving；完成後為 200 OK、狀態 left。可以重複呼叫。

即使這個請求失敗，客戶端也要先斷開媒體、停止採集。服務端會繼續回收；回收完成前，使用者再次加入可能暫時提示正在其他頻道中。

錯誤

不是本次登入的會話時返回 404 not_found。登入失效時按認證錯誤處理，不要換成另一個使用者的登入去操作原來的會話。

資料結構

Session（會話）

欄位	說明
`session_id`	會話 ID，字串
`channel_id`、`username`、`role`	頻道、使用者和角色
`status`	`joining`、`joined`、`leaving`、`left`
`version`	會話的版本號
`reserved_at`、`join_deadline`、`max_expires_at`	保留席位的時間、加入截止時間、最晚結束時間
`joined_at`、`leaving_at`、`left_at`	入會、開始退出、退出完成的時間
`leave_reason`	退出的原因
`media_connected`、`media_observed_at`	服務端觀察到的媒體連線狀態和觀察時間
`client_session_id`	加入時提交的 ID，只在本人的響應中返回

Participant（成員）

session_id、username、role、status、joined_at、version、media_connected、media_observed_at、media_identity。不含裝置和登入資訊。

media_identity 是成員在媒體房間中的標識，用來把收到的音影片軌道準確對應到成員。它不是使用者名稱，也不能用來入會。

MediaCredential（媒體憑據）

provider（為 livekit）、url、room、identity、token、expires_at。只發給會話的本人。

時間格式同接入概述，還沒發生的時間為 null。media_connected 為 true、false 或 null，null 表示暫時無法確認。不要持久儲存票據和媒體 Token；這些響應都帶 Cache-Control: no-store。

客戶端頻道會話 ​

加入頻道 ​

路徑引數 ​

請求體 ​

請求示例 ​

響應 ​

錯誤 ​

查詢本人當前會話 ​

請求示例 ​

響應 ​

錯誤 ​

查詢頻道 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢頻道成員 ​

路徑引數 ​

查詢引數 ​

請求示例 ​

響應 ​

錯誤 ​

查詢本人會話 ​

路徑引數 ​

請求示例 ​

響應 ​

錯誤 ​

續發媒體憑據 ​

路徑引數與請求體 ​

請求示例 ​

響應 ​

錯誤 ​

心跳 ​

路徑引數與請求體 ​

請求示例 ​

響應 ​

錯誤 ​

退出 ​

路徑引數與請求體 ​

請求示例 ​

響應 ​

錯誤 ​

資料結構 ​

Session（會話） ​

Participant（成員） ​

MediaCredential（媒體憑據） ​

客戶端頻道會話

加入頻道

路徑引數

請求體

請求示例

響應

錯誤

查詢本人當前會話

請求示例

響應

錯誤

查詢頻道

路徑引數

請求示例

響應

錯誤

查詢頻道成員

路徑引數

查詢引數

請求示例

響應

錯誤

查詢本人會話

路徑引數

請求示例

響應

錯誤

續發媒體憑據

路徑引數與請求體

請求示例

響應

錯誤

心跳

路徑引數與請求體

請求示例

響應

錯誤

退出

路徑引數與請求體

請求示例

響應

錯誤

資料結構

Session（會話）

Participant（成員）

MediaCredential（媒體憑據）