頻道票據

訪問方式為 ticket 的頻道，使用者要憑票據才能加入。你的服務端為指定使用者簽發票據，再透過你自己的業務介面（如“進入會議”介面的響應）交給這個使用者，使用者的客戶端帶上票據加入。

特點	說明
繫結	每張票據繫結本應用的一個使用者、一個頻道和一個角色，別人拿到也用不了
一次性	加入成功一次後就失效
有效期	30 到 300 秒，預設 120 秒，簽發後要儘快交給使用者
不是登入憑證	使用者仍要先登入 IM，票據不能代替 User Token。open 頻道不接收票據

票據只交給繫結的使用者本人，不要放在 URL、IM 訊息、日誌或客戶端的持久快取裡。

簽發票據

為 1 到 50 個使用者簽發票據。給同一個使用者重新簽發時，他在這個頻道還沒用過的舊票據隨之失效。

POST/{org_name}/{app_name}/rtc/channels/{channel_id}/tickets

路徑引數

org_name、app_name 見接入概述，channel_id 見頻道管理。

請求體

欄位	型別	必填	說明
users	Array	是	1 到 50 個使用者，不能重複
users[].username	String	是	使用者名稱，必須是本應用已存在、未被封禁的使用者
users[].role	String	否	publisher 或 subscriber；省略時取頻道的 default_role。建議明確給出
ttl_seconds	Integer	否	有效期，30 到 300 秒，預設 120

請求示例

curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/tickets" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"users":[{"username":"alice","role":"publisher"},{"username":"bob","role":"subscriber"}],"ttl_seconds":120}'

響應

成功返回 201 Created，tickets 中每個使用者一項：username、role、ticket（票據）、expires_at（過期時間）。整批先檢查，有一個使用者不合法就都不簽發。重新簽發不改變已經在頻道里的會話的角色。

不要自動重試

簽發不是冪等的：每次請求都會讓同一使用者之前的票據失效。響應丟失時，由你的業務決定是否重新簽發，並把最新的票據交給使用者。

錯誤

HTTP 狀態碼	code	說明
400	invalid_argument	頻道不是 ticket 頻道；使用者重複；使用者數、ttl_seconds 或角色不合法
404	not_found	頻道或使用者不存在
403	user_disabled	使用者被封禁
403	permission_denied	使用者被這個頻道封禁，或應用的音影片、頻道功能不可用
409	conflict	頻道已關閉或已到期
429	rate_limited	簽發太頻繁，按 Retry-After 等待後再試

撤銷未消費票據

讓使用者還沒用過的票據失效，例如取消某人的參會資格。已經加入的會話不受影響；要讓他離開或不能再進來，使用移出或封禁。

POST/{org_name}/{app_name}/rtc/channels/{channel_id}/tickets/revoke

路徑引數

同簽發票據。

請求體

欄位	型別	必填	說明
operation_id	String	是	這次操作的 ID，1 到 64 個可列印 ASCII 字元，不能有空格。重試時保持不變
usernames	Array<String>	是	1 到 50 個使用者名稱，不能重複
reason	String	否	說明，最多 256 個字元

請求示例

curl -X POST "$IM_API/$ORG/$APP/rtc/channels/meeting-demo/tickets/revoke" \
  -H "Authorization: Bearer $APP_TOKEN" -H "Content-Type: application/json" \
  -d '{"operation_id":"revoke-meeting-demo-alice-001","usernames":["alice"],"reason":"取消入会资格"}'

響應

成功返回 200 OK，包括 operation_id 和撤銷的票據數 revoked_count。

錯誤

用同一個 operation_id、同樣的引數重試，返回第一次的結果。

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

客戶端票據錯誤

客戶端加入頻道時，票據缺失、已失效、已過期、已用過，或者繫結的不是這個使用者、頻道，都返回 404 not_found，details.reason 為 channel_not_found，與頻道不存在相同。這樣別人無法透過錯誤提示試探出哪些受控頻道存在。

客戶端提示“無法加入”即可，需要時向你的服務端重新申請票據。加入成功後重試同一個請求、或恢復已有會話的方式，見客戶端頻道會話。