Skip to main content

设置回调

POST /server/v1/channel/set-callback 鉴权:需要(见概览 注册回调地址,RTC 侧在频道/用户状态变化时通知你的业务后端。 所有事件皆可不订阅,未订阅的事件不会推送。 完整的事件清单、每个事件的字段结构,以及回调必须怎么应答,见「回调事件接入指南」。 请求参数
string
应用场景(外部业务调用时不需要此参数)
array<string>
监听事件列表,取值见「回调事件接入指南」 示例:["user_join","user_leave","channel_destroy"]
string
回调地址,需可公网访问 示例:https://your-domain.com/server/v1/callback/rtc
请求示例:
响应参数 data 为 null 响应示例:

获取加入频道token

POST /server/v1/channel/grant 鉴权:需要(见概览 接入 RTC 的第一个接口。典型时序:业务后端确认用户有权进入某个频道 → 调本接口拿到 token 与 sid → 把 token 下发给客户端,客户端用它调 SDK 的 joinChannel。 token 与 channel+uid 绑定且有有效期,不要缓存复用,每次入会都重新获取。 频道无需预先创建,第一个人成功加入时自动打开。
  • 同一个 uid 重复获取 token 会得到新的 sid;若该 uid 已在会中,新会话会把旧会话顶下线
  • is_audience 为 true 的用户只收流、不广播,也不出现在默认的成员列表里(需要 with_audience 才能查到)
请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
必填
第三方用户ID(仅支持大小写字母、数字、下划线 _ 与连字符 -)(最大长度 100) 示例:1001
string
必填
会中昵称(最大长度 100) 示例:张三
object
用户扩展属性 示例:{"avatar":"https://cdn.example.com/avatar/1001.png"}
boolean
是否观众,类似研讨会观众,只收流,不参与互动,不广播
string
线路,取值是中文线路名,由部署的网络配置决定;留空则由服务端选择 示例:内网
string
服务分组
请求示例:
响应参数
string
本次会话 ID,由服务端生成,用于按会话维度查询与对账
string
入会凭证,下发给客户端调用 SDK 的 joinChannel
响应示例:

获取频道详情

POST /server/v1/channel/detail 鉴权:需要(见概览 查询单个频道的当前状态与扩展属性。只能查到已打开的频道 —— 频道未打开或已销毁时 返回空,需要历史信息请用「频道记录」。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
请求示例:
响应参数
string
应用id
string
频道名
object
频道扩展属性
integer
频道创建时间 示例:1718250917
integer
频道信息最后变更时间 示例:1718250921
响应示例:

获取频道用户详情

POST /server/v1/channel/user-detail 鉴权:需要(见概览 查询频道内单个成员的实时状态,包括他当前发布的流轨道(stream_tracks)。 同一个 uid 多端在线时,返回的是其中一个会话;需要区分具体设备请用 「在线/离线成员列表」按 sid 取。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
必填
第三方用户ID(仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:1001
请求示例:
响应参数
string
应用id
string
用户id
string
会中昵称
integer
设备类型
string
设备ID
string
客户端RTCsdk版本号
object
用户扩展属性
string
线路号
string
服务器分组id
integer
用户信息最后变更时间,秒级时间戳 示例:1718250918
string
频道名
string
会话id
boolean
是否观众,类似研讨会观众,只收流
integer
进入时间
integer
退出时间
array<object>
流轨道
响应示例:

在线频道列表

POST /server/v1/channel/list 鉴权:需要(见概览 分页列出当前已打开的频道。频道在第一个用户加入时自动打开,最后一人离开 2 小时后 自动销毁,因此这里只反映当下的活跃情况;要查历史请用「频道记录」。 请求参数
boolean
是否包括详情。false 时只返回频道名等基础字段,可显著降低响应体积;需要扩展属性与流媒体参数时再置 true
integer
页数,从1开始 示例:1
integer
每页数据量 示例:10
请求示例:
响应参数
string
应用id
string
频道名
object
频道扩展属性
integer
频道创建时间 示例:1718250917
integer
频道信息最后变更时间 示例:1718250921
响应示例:

在线/离线成员列表

POST /server/v1/channel/list-user 鉴权:需要(见概览 分页列出频道成员。同一个 uid 从多个端进入会有多条记录,用 sid 区分不同会话。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
boolean
获取在线还是离线成员列表。false(默认)返回当前在线的成员,true 返回已离开的成员
boolean
是否包括隐身观众。观众默认不返回,需要显式传 true
integer
页数,从1开始 示例:1
integer
每页数据量 示例:10
请求示例:
响应参数
string
应用id
string
用户id
string
会中昵称
integer
设备类型
string
设备ID
string
客户端RTCsdk版本号
object
用户扩展属性
string
线路号
string
服务器分组id
integer
用户信息最后变更时间,秒级时间戳 示例:1718250918
string
频道名
string
会话id
boolean
是否观众,类似研讨会观众,只收流
integer
进入时间
integer
退出时间
array<object>
流轨道
响应示例:

在线/离线成员Uids

POST /server/v1/channel/list-uids 鉴权:需要(见概览 与「在线/离线成员列表」的筛选条件完全一致,但只返回 uid 字符串数组,不含成员详情。 适合只需要判断”谁在会中”的场景(如权限校验、名单比对),响应体积比完整列表小一个数量级。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
boolean
获取在线还是离线成员列表。false(默认)返回当前在线的成员,true 返回已离开的成员
boolean
是否包括隐身观众。观众默认不返回,需要显式传 true
integer
页数,从1开始 示例:1
integer
每页数据量 示例:10
请求示例:
响应参数
array<string>
返回数据
响应示例:

变更频道信息

POST /server/v1/channel/update 鉴权:需要(见概览 更新频道的扩展属性。频道必须已打开,否则更新无效。 变更会通过信令同步给会中所有客户端。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
object
频道扩展属性。整体替换语义,不是字段级合并 —— 需要保留的字段请一并传入 示例:{"watermark_disabled":true}
请求示例:
响应参数 data 为 null 响应示例:

变更用户信息

POST /server/v1/channel/update-user 鉴权:需要(见概览 更新会中成员的昵称、扩展属性或观众身份。变更会同步给会中其他成员。 把已在会中的成员改成观众会让他退化为只收流,其已发布的流轨道会被停止。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
必填
用户id(仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:1001
string
会中昵称,不传表示不改 示例:张三
object
用户扩展属性,整体替换语义 示例:{"avatar":"https://cdn.example.com/avatar/1001.png"}
boolean
是否观众,类似研讨会观众,只收流
array<object>
流轨道
请求示例:
响应参数 data 为 null 响应示例:

发送自定义消息

POST /server/v1/channel/send-custom-msg 鉴权:需要(见概览 通过信令通道向频道内广播一条自定义消息,客户端 SDK 会以事件形式收到。 适合做聊天、举手、投票这类轻量业务信令,不适合传大数据或高频消息。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
必填
消息命令,由你自定义,客户端按它分发处理 示例:chat
any
消息体,任意 JSON,结构由你定 示例:&#123;"text": "i love srtc"&#125;
string
发送者ID,用于客户端展示”谁发来的”;服务端下发的系统消息可留空(仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:1001
string
发送者昵称 示例:张三
array<string>
接收者ID列表(空时给全频道发) 示例:["1002","1003"]
boolean
是否重要,重要消息在断线重连后会重发确保收到,代价是延迟略高
请求示例:
响应参数 data 为 null 响应示例:

踢人

POST /server/v1/channel/kick-user 鉴权:需要(见概览 把指定成员踢出频道。该成员的客户端会收到被踢事件,并触发 user_leave 回调 (reason 标识为被踢)。 踢出是一次性操作,不会拉黑 —— 被踢的 uid 重新获取 token 后仍可再次进入。 需要禁止再入请在你自己的业务侧拦截 token 发放。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
必填
第三方用户ID(仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:1001
请求示例:
响应参数 data 为 null 响应示例:

手动打开频道

POST /server/v1/channel/open 鉴权:需要(见概览 默认情况下第一个用户加入频道时会自动打开频道,无需调用本接口。 只有一种场景需要它:你想在任何人进入之前就设置好频道的扩展属性(如水印开关、 业务侧的房间配置),这样第一个人进来时就能读到正确的配置,避免”先进来再改属性” 的时序问题。 频道开启后 2 小时内无人加入,或最后一个用户离开 2 小时后,会自动销毁。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
object
频道扩展属性 示例:{"watermark_disabled":true}
请求示例:
响应参数 data 为 null 响应示例:

销毁频道

POST /server/v1/channel/destroy 鉴权:需要(见概览 立即销毁频道,会中所有人被强制退出,会触发 channel_destroy 回调。 正常情况下频道会在最后一人离开 2 小时后自动销毁,不需要手动调用。本接口用于需要 立即回收频道的场景(如会议被管理员强制结束)。频道内进行中的录制任务会一并停止。 销毁后同名频道可以重新打开,但会是一条新的频道记录。 请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
请求示例:
响应参数 data 为 null 响应示例:

频道记录

POST /server/v1/channel/list-record 鉴权:需要(见概览 查询频道的历史开启记录。同一个频道名多次开启会有多条记录,每条对应一个完整的 生命周期(open_at → destroy_at)。响应里 destroy_at 为 0 表示该频道仍在进行中。 请求参数
string
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
integer
起始时间,秒级时间戳,按频道开启时间过滤;0 表示不限 示例:1718194666
integer
终止时间,秒级时间戳;0 表示不限 示例:1718799878
string
排序(可排序字段:open_at、destroy_at)
integer
页数,从1开始 示例:1
integer
每页数据量 示例:10
请求示例:
响应参数
string
频道记录ID 示例:snp3rp
string
应用id
string
频道
object
扩展属性
integer
开启时间
integer
销毁时间
integer
销毁原因
响应示例:

出入频道记录

POST /server/v1/channel/list-user-record 鉴权:需要(见概览 查询成员的进出频道记录,单人多次进入会有多条记录,用 sid 区分。 这是做时长计费、参会审计的主要数据源。
  • 响应里 leave_at 为 0 表示该成员仍在会中
  • 单次参会时长 = leave_at - join_at(秒)
请求参数
string
必填
频道名(长度 64 字节以内,仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:fire
string
用户id,留空表示不限(仅支持大小写字母、数字、下划线 _ 与连字符 -) 示例:1001
string
会中昵称,留空表示不限 示例:张三
integer
起始时间,秒级时间戳,按进入时间过滤;0 表示不限 示例:1718194666
integer
终止时间,秒级时间戳;0 表示不限 示例:1718799878
boolean
是否包括隐身观众
string
排序(可排序字段:join_at、leave_at)
integer
页数,从1开始 示例:1
integer
每页数据量 示例:10
请求示例:
响应参数
string
出入记录ID 示例:syd30d
string
应用id
string
频道
string
会话id,同一 uid 多次进入靠它区分 示例:ff6u9joh5c1a0toa7dj1
string
用户id 示例:1001
string
会中昵称
boolean
是否观众,类似研讨会观众,只收流
integer
设备类型
string
设备ID
string
客户端RTCsdk版本号
object
扩展属性
integer
进入时间
integer
退出时间
integer
退出原因
响应示例:

查询在线人数

POST /server/v1/channel/online-user-num 鉴权:需要(见概览 批量查询多个频道的当前在线人数,一次请求即可,适合列表页展示。 响应的 data 是「频道名 → 人数」的映射,如 {"fire": 4};未打开或不存在的频道 不会出现在结果里(而不是返回 0),需要区分请自行对照请求的 channels。 请求参数
array<string>
必填
频道名列表 示例:["fire","water"]
boolean
是否包括隐身观众
请求示例:
响应参数
integer
键为动态值,见上方说明
响应示例:

查询频道历史参与人数

POST /server/v1/channel/history-join-num 鉴权:需要(见概览 统计一个频道在指定时间范围内的历史参与规模。
  • user_num 按 uid 去重,回答”有多少人参加过”
  • user_times 不去重,回答”一共进出了多少次”
请求参数
string
必填
频道名 示例:fire
integer
必填
起始时间,秒级时间戳 示例:1718194666
integer
终止时间,秒级时间戳;0 表示统计到当前时刻 示例:1718799878
boolean
是否包括隐身观众
请求示例:
响应参数
integer
参会人数,按uid去重 示例:60
integer
参会人次,同一人多次进入累计 示例:1935
响应示例:

今日频道统计

POST /server/v1/channel/today 鉴权:需要(见概览 你自己应用今日的频道开启次数与累计时长汇总。无请求参数 —— 统计范围由鉴权得到的 应用身份决定,只会返回属于你的数据。 只统计已销毁的频道(destroy_at 大于 0),进行中的频道不计入,因此数值会随当天推进 而增长。时区固定为东八区(Asia/Shanghai)。 请求参数 响应参数
integer
统计时刻,响应生成时的秒级时间戳 示例:1718250917
integer
今日频道开启次数 示例:120
integer
今日频道累计时长(秒) 示例:43200
响应示例:

频道统计(按天聚合)

POST /server/v1/channel/stats 鉴权:需要(见概览 按天聚合的频道开启次数与时长,用于画趋势图。统计范围由鉴权得到的应用身份决定, 只返回你自己应用的数据。
  • 只统计已销毁的频道(destroy_at 大于 0),进行中的不计入
  • 没有数据的日期不会出现在结果里(不补零),画图时需自行填充
请求参数
integer
起始时间,秒级时间戳;0 表示统计最近 31 天 示例:1718194666
integer
终止时间,秒级时间戳;0 或超过当前时间按当前时间处理 示例:1718799878
请求示例:
响应参数
string
日期,格式 YYYY-MM-DD 示例:2024-06-12
integer
当日频道开启次数 示例:120
integer
当日频道累计时长(秒) 示例:43200
响应示例: