頻道管理
你的服務端用 App Token 建立、查詢、修改和關閉本應用的頻道。頻道是什麼、怎麼選擇訪問方式見獨立 RTC 頻道；請求地址、鑑權、分頁和時間格式見接入概述。
| 要做什麼 | 介面 |
|---|---|
| 開一場會議或語音房 | 建立頻道 |
| 列出進行中的頻道 | 查詢頻道列表 |
| 看頻道的人數和狀態 | 查詢頻道 |
| 改名稱、業務欄位或到期時間 | 修改頻道 |
| 會議結束，讓所有人退出 | 關閉頻道 |
客戶端只需要拿到 channel_id 和發給本人的票據，不要把 App Token 交給客戶端。
建立頻道
用你指定的 channel_id 建立頻道。可以安全地重試：同一個 ID、同樣的引數、頻道還開放時，返回已有的頻道，不重複建立。
/{org_name}/{app_name}/rtc/channels/{channel_id}路徑引數
org_name、app_name 見請求地址。
| 引數 | 型別 | 說明 |
|---|---|---|
channel_id | String | 頻道 ID，1 到 64 個 ASCII 字元：第一個字元為字母或數字，其餘為字母、數字、_ 或 -。區分大小寫 |
請求體
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
name | String | 是 | 名稱，去掉首尾空白後不能為空，最多 128 個字元，不能包含控制字元。按應用的設定做內容稽核 |
media | String | 是 | audio 語音或 video 影片 |
access_mode | String | 否 | ticket 憑票據加入（預設）或 open 登入使用者都能加入，見訪問方式與角色 |
default_role | String | 否 | 預設角色：publisher 釋出者（預設）或 subscriber 訂閱者 |
max_participants | Integer | 否 | 人數上限，1 到 64，預設 16 |
expires_at | String / null | 否 | 到期時間，必須晚於當前時間；省略或為 null 表示不到期 |
ext | Object | 否 | 業務擴充套件欄位，預設為空物件，JSON 不超過 4 KB，不能為 null |
media、access_mode、default_role 和 max_participants 建立後不能修改。
請求示例
curl -X PUT "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" \
-H "Authorization: Bearer $APP_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"项目会议","media":"video","access_mode":"ticket","default_role":"publisher","max_participants":16,"ext":{}}'響應
| 情況 | 返回 |
|---|---|
| 首次建立 | 201 Created，channel 為頻道物件 |
重試：同一個 ID、同樣的引數，頻道仍為 open | 200 OK，返回已有的頻道 |
| 同一個 ID 但引數不同，或這個 ID 的頻道已關閉 | 409，見下方錯誤 |
錯誤
| HTTP 狀態碼 | code | details.reason | 說明 |
|---|---|---|---|
| 400 | invalid_argument | invalid_channel_id、invalid_request、invalid_role | 頻道 ID、引數或角色不合法 |
| 409 | already_exists | channel_id_used | 這個 ID 已被其他引數的頻道或已關閉的頻道使用 |
| 409 | limit_exceeded | channel_limit | 應用開放的頻道數已達上限，見使用限制 |
| 403 | permission_denied | rtc_disabled 等 | 應用沒有開通音影片，或頻道功能沒有開啟 |
名稱沒有透過稽核，以及認證、限流等通用錯誤，見錯誤碼。
查詢頻道列表
/{org_name}/{app_name}/rtc/channels路徑引數
org_name、app_name 同上。
查詢引數
| 引數 | 型別 | 必填 | 說明 |
|---|---|---|---|
status | String | 否 | open、closing 或 closed；省略時返回全部 |
limit | Number | 否 | 每頁的條數，見分頁 |
cursor | String | 否 | 上一頁返回的 next_cursor。換了 status 後不能沿用 |
請求示例
curl "$IM_API/$ORG/$APP/rtc/channels?status=open&limit=20" -H "Authorization: Bearer $APP_TOKEN"響應
成功返回 200 OK：items 為頻道物件的陣列，next_cursor 為下一頁的遊標，最後一頁為 null。
錯誤
status 或遊標不合法時返回 400 invalid_argument；其他見錯誤碼。
查詢頻道
/{org_name}/{app_name}/rtc/channels/{channel_id}路徑引數
org_name、app_name、channel_id 同建立頻道。
請求示例
curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" -H "Authorization: Bearer $APP_TOKEN"響應
成功返回 200 OK，channel 為頻道物件。不返回任何媒體 Token。
錯誤
頻道不存在或不屬於本應用時返回 404 not_found。
修改頻道
修改頻道的名稱、業務欄位或到期時間。只能修改還開放、沒有到期的頻道。
/{org_name}/{app_name}/rtc/channels/{channel_id}路徑引數
同建立頻道。
請求體
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
version | Integer | 是 | 最近讀取到的頻道 version |
name | String | 否 | 新名稱，規則同建立 |
ext | Object | 否 | 新的業務擴充套件欄位，整體替換 |
expires_at | String / null | 否 | 新的到期時間；null 表示取消到期 |
name、ext、expires_at 至少給出一項，沒有給出的不變。其他欄位不能修改，請求中有不認識的欄位時拒絕。
請求示例
把 version 換成你讀取到的值：
curl -X PATCH "$IM_API/$ORG/$APP/rtc/channels/meeting-demo" \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"version":1,"name":"产品会议","expires_at":null}'響應
成功返回 200 OK，channel 為修改後的頻道。有實際變化時 version 加一，值沒有變化時不變。
錯誤
| HTTP 狀態碼 | code | 說明 |
|---|---|---|
| 400 | invalid_argument | 欄位不合法 |
| 409 | version_conflict | version 不是最新的，重新查詢後再改 |
| 409 | conflict | details.reason 為 channel_closed：頻道已關閉或已到期 |
關閉頻道
關閉頻道：立即不能再加入，已有成員開始退出。關閉後不能重新開啟，頻道 ID 也不能再用。
/{org_name}/{app_name}/rtc/channels/{channel_id}/close路徑引數
同建立頻道。
請求體
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
reason | String | 是 | 關閉的說明，不能為空，最多 256 個字元。只用於管理，不會發給頻道中的客戶端 |
請求示例
curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/close" \
-H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
-d '{"reason":"会议结束"}'響應
返回 channel：
| 狀態碼 | status | 含義 |
|---|---|---|
202 Accepted | closing | 已不能加入，成員和媒體還在清理，服務端會持續重試。這時不能當作所有人的媒體都已斷開 |
200 OK | closed | 清理完成 |
重複關閉是安全的，返回頻道當前的狀態。
錯誤
頻道不存在時返回 404 not_found；引數不合法時返回 400 invalid_argument。
資料結構
Channel
| 欄位 | 型別 | 說明 |
|---|---|---|
channel_id | String | 你指定的頻道 ID |
channel_uid | String | 服務端生成的唯一 ID。按字串儲存 |
name | String | 名稱 |
media | String | audio 或 video |
access_mode | String | ticket 或 open |
default_role | String | publisher 或 subscriber |
status | String | open 開放、closing 關閉中、closed 已關閉 |
max_participants | Integer | 人數上限 |
seat_count | Integer | 佔用的席位數，包括加入中、退出中的成員 |
joined_count | Integer | 最近一次確認的媒體線上人數 |
media_state | String | 媒體房間的狀態：idle 沒人、preparing 準備中、active 進行中、unknown 暫時無法確認、reclaiming 回收中 |
media_observed_at | String / null | 最近一次確認媒體狀態的時間 |
generation | Integer | 媒體房間的代次，每次重新準備媒體房間加一 |
version | Integer | 頻道資料的版本號，用於修改頻道 |
members_version | Integer | 成員列表的版本號，成員變化時加一 |
ext | Object | 業務擴充套件欄位 |
expires_at | String / null | 到期時間 |
closing_at | String / null | 開始關閉的時間 |
closed_at | String / null | 關閉完成的時間 |
created_at、updated_at | String | 建立、最近一次修改的時間 |
close_reason | String | 關閉原因的程式碼 |
close_note | String | 關閉時填寫的說明，只在服務端介面中返回 |
人數和 unknown 狀態的顯示方式見生命週期與佔用。頻道資料和授權相關的響應都不允許快取。