频道票据

票据用于 ticket 频道，绑定本应用的指定用户、频道和角色，只允许消费一次。票据不能代替 IM User Token；开放频道不接收票据。票据原文只交给绑定用户，不放在 URL、IM 消息、日志或持久客户端缓存中。

签发票据

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

路径参数

org_name、app_name 见接入概述，channel_id 见频道管理。使用 App Token。

请求体

字段	类型	必填	说明
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：tickets 数组，每项有 username、role、ticket、expires_at。整批校验后签发；新签发会撤销该用户在本频道尚未消费的旧票据，不改变已加入会话的角色。

签发不是幂等操作，不自动重试。 响应丢失后，由业务明确决定重签并交付最新票据，不能假设旧票据仍有效。

错误

HTTP / code	说明
400 / invalid_argument	非 ticket 频道、重复用户、数量 / TTL / 角色无效
404 / not_found	频道或目标用户不存在
403 / user_disabled	目标用户不可用
403 / permission_denied	目标用户被频道封禁，或 RTC / 频道不可用
409 / conflict	频道关闭或到期
429 / rate_limited	签发频率超限，遵循 Retry-After

撤销未消费票据

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

路径参数

同签发接口。

请求体

字段	类型	必填	说明
operation_id	String	是	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：operation_id 与 revoked_count。只撤销未消费票据，不结束已加入的会话；要禁止继续参与，使用移出或封禁。

错误

同操作者的相同键、参数重放返回原结果；相同键用于不同参数为 409 conflict/idempotency_conflict。无效参数为 400 invalid_argument，资源不存在为 404 not_found。

客户端票据错误

新加入时，缺少、失效、过期、已消费或绑定不匹配的票据，统一按 404 not_found/channel_not_found 处理，以免泄露频道是否存在。不能依靠不同错误提示枚举受控频道。首次成功加入的同键重放有独立会话校验，恢复已有会话使用会话续凭据接口，见客户端会话。