頻道會話與成員管理

你的服務端用 App Token 檢視頻道中有誰，把某人移出頻道，或封禁他不讓再進來。這些介面中的使用者名稱都是本應用的使用者名稱，不是媒體房間中的 media_identity；它們也不會替使用者簽發媒體憑據。路徑字首和分頁見接入概述。

要做什麼	介面	效果
看頻道里有誰	查詢頻道會話
讓某人離開這一次	移出使用者	結束他當前的會話，之後還能再加入
讓某人不能再進來	封禁使用者	結束他當前的會話，撤銷他沒用過的票據，之後不能加入
取消某人還沒用的入會資格	撤銷票據	不影響已經加入的會話
恢復被封禁的使用者	解除封禁	ticket 頻道要重新簽發票據

查詢頻道會話

GET/{org_name}/{app_name}/rtc/channels/{channel_id}/sessions

路徑引數

org_name、app_name、channel_id 見頻道管理。

查詢引數

引數	型別	必填	說明
status	String	否	joining、joined、leaving 或 left。省略時返回前三種（當前在頻道中的）；要查已退出的會話，傳 status=left
limit	Number	否	每頁的條數，見分頁
cursor	String	否	上一頁返回的 next_cursor

請求示例

curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/sessions?status=joined&limit=20" -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：items 為會話的陣列，next_cursor 在最後一頁為 null。會話的欄位見客戶端頻道會話，這裡另外返回移出、封禁時填寫的說明 leave_note。已退出的會話保留 90 天。

錯誤

status 或遊標不合法時返回 400 invalid_argument；頻道不存在時返回 404 not_found。

移出使用者

結束使用者在頻道中的當前會話。他之後仍可以再加入，沒用過的票據也還有效。

POST/{org_name}/{app_name}/rtc/channels/{channel_id}/members/{username}/remove

路徑引數

org_name、app_name、channel_id 同上。

引數	型別	說明
username	String	要移出的使用者名稱

請求體

欄位	型別	必填	說明
operation_id	String	是	這次操作的 ID，1 到 64 個可列印 ASCII 字元，不能有空格。超時後用同一個 ID 重試
reason	String	是	說明，不能為空，最多 256 個字元

請求體中不能有 usernames。

請求示例

curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/members/alice/remove" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"operation_id":"remove-meeting-demo-alice-001","reason":"主持人移出"}'

響應

返回 operation_id 和被結束的會話 sessions。媒體還在清理時為 202 Accepted，完成後為 200 OK。用同一個 operation_id、同樣的引數重試，不會重複執行。

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	引數不合法
404	not_found	頻道或使用者不存在
409	conflict	details.reason 為 idempotency_conflict：同一個 operation_id 用於不同的引數

查詢使用者封禁

查詢使用者在這個頻道的封禁記錄，拿到修改、解除封禁時要用的 version。

GET/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}

路徑引數

同移出使用者。

請求示例

curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK，ban 為封禁記錄，從沒封禁過時為 null。記錄可能已解除或已到期，按 status 和 expires_at 判斷現在是否有效。

錯誤

頻道或使用者不存在時返回 404 not_found。

封禁使用者

封禁使用者：他當前的會話開始退出，沒用過的票據失效，之後不能再加入這個頻道。也用於修改已有封禁的期限和說明。

PUT/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}

路徑引數

同移出使用者。

請求體

欄位	型別	必填	說明
version	Integer	是	沒有封禁記錄時為 0；已有記錄時為查詢使用者封禁讀到的 version
reason	String	是	說明，不能為空，最多 256 個字元
expires_at	String / null	否	到期時間，必須晚於當前時間；省略或為 null 表示永久封禁

請求示例

這個使用者還沒有封禁記錄：

curl -X PUT "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"version":0,"reason":"违规参与","expires_at":null}'

響應

返回 ban：首次封禁為 201 Created，修改或同樣的請求重試為 200 OK。返回成功時媒體可能還在斷開中。

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	引數不合法
409	version_conflict	version 不是最新的，重新查詢後再提交
409	conflict	details.reason 為 channel_closed：頻道已關閉

解除封禁

DELETE/{org_name}/{app_name}/rtc/channels/{channel_id}/bans/{username}

路徑引數

同移出使用者。

請求體

欄位	型別	必填	說明
version	Integer	是	查詢使用者封禁讀到的最新 version

請求示例

curl -X DELETE "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans/alice" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"version":1}'

響應

成功返回 200 OK，ban 為解除後的記錄，本來就沒有記錄時為 null。重複解除也返回成功。

解除不會恢復封禁時失效的票據或已結束的會話：ticket 頻道要重新簽發票據。

錯誤

version 不是最新的時返回 409 version_conflict，這樣用舊的版本號不會誤解除之後新加的封禁。

查詢有效封禁列表

列出頻道中現在有效的封禁。要看已解除、已到期的記錄，用查詢使用者封禁。

GET/{org_name}/{app_name}/rtc/channels/{channel_id}/bans

路徑引數

同查詢頻道會話。

查詢引數

limit、cursor，見分頁。

請求示例

curl "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/bans?limit=20" -H "Authorization: Bearer $APP_TOKEN"

響應

成功返回 200 OK：items 為現在有效的封禁記錄，next_cursor 在最後一頁為 null。

錯誤

遊標不合法時返回 400 invalid_argument；頻道不存在時返回 404 not_found。

資料結構

Ban（封禁記錄）：

欄位	型別	說明
username	String	使用者名稱
status	String	active 封禁中、revoked 已解除。active 的還要看 expires_at 是否已過
expires_at	String / null	到期時間，null 為永久
reason	String	封禁的說明。只用於管理，不會出現在客戶端的成員列表或媒體憑據中
version	Integer	版本號，修改和解除時使用
created_at、updated_at	String	建立、最近一次修改的時間