频道管理
使用 App Token 操作本应用频道。请求地址、鉴权、分页、ID 和时间格式见接入概述。客户端只接收 channel_id 和自己的票据，不应持有 App Token。
创建频道
/{org_name}/{app_name}/rtc/channels/{channel_id}路径参数
org_name、app_name 见请求地址。channel_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 |
请求示例
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 和 channel。同一 ID、相同规范化创建参数且频道仍为 open 时重放返回 200，不重复创建。不同参数或已关闭的 ID 返回冲突。频道对象见本页数据结构。
错误
| 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 可选 open、closing、closed，省略查询全部；cursor、limit 遵循分页约定，游标不能换筛选条件复用。
请求示例
curl "$IM_API/$ORG/$APP/rtc/channels?status=open&limit=20" -H "Authorization: Bearer $APP_TOKEN"响应
200：items 为频道数组，next_cursor 为下一页游标，最后一页为 null。
错误
无效状态或游标返回 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：channel 为频道对象。查询不会返回媒体 Token。
错误
频道不存在或不属于本应用返回 404 not_found。
修改频道
/{org_name}/{app_name}/rtc/channels/{channel_id}路径参数
同创建接口。
请求体
version 必填，使用最新频道版本。name、ext、expires_at 至少提供一项，范围同创建；省略表示不改，ext 整体替换，expires_at:null 清除期限。其他创建字段不可修改，未知字段拒绝。只允许修改仍开放且未到期的频道。
请求示例
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：返回最新 channel。实际修改增加版本，同值修改不增加版本。
错误
版本不一致为 409 version_conflict；已关闭或到期为 409 conflict/channel_closed；无效字段为 400 invalid_argument。
关闭频道
/{org_name}/{app_name}/rtc/channels/{channel_id}/close路径参数
同创建接口。
请求体
必须提交 reason，为非空管理说明，最多 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。清理中为 202、status=closing；已完成为 200、status=closed。关闭立即禁止新加入，但清理可能持续重试；202 不能当作媒体已经全部断开。重复关闭可重放，业务频道不能重新打开或复用 ID。
错误
频道不存在为 404 not_found；参数无效为 400 invalid_argument。
数据结构
Channel
| 字段 | 类型 | 说明 |
|---|---|---|
channel_id、channel_uid | String | 业务 ID 与唯一资源 ID；均保留字符串 |
name、media、access_mode、default_role | String | 名称、媒体、访问方式和默认角色 |
status | String | open、closing、closed |
max_participants、seat_count、joined_count | Integer | 上限、占位数、最近确认媒体在线数 |
media_state | String | idle、preparing、active、unknown、reclaiming |
media_observed_at | String / null | 最近媒体观察时间 |
generation、version、members_version | Integer | 媒体代次、频道资料版本、成员列表版本；各有用途 |
ext | Object | 业务扩展字段 |
expires_at、closing_at、closed_at | String / null | 到期、开始关闭、关闭完成时间 |
created_at、updated_at | String | 创建和更新时间 |
close_reason | String | 关闭原因代码 |
close_note | String | 仅管理响应包含的处置说明 |
人数与未知媒体状态的显示规则见频道概述。资料和授权相关响应禁止缓存。