Skip to main content
回调让你的业务后端在不轮询的前提下感知会议侧的变化。注册地址用设置事件通知, 所有事件皆可不订阅,未订阅的事件不会推送

请求形态

我们向你注册的 cb_url 发 POST 请求,事件名同时出现在查询参数与请求体里:
各事件的差异只在 data,外层三个字段恒定。time 是事件发生的秒级时间戳。

验签(务必做)

回调请求头带的签名与调用服务端 API 时的算法完全一致(见概览), 只是方向相反:这次是我们用你的 app_key 签名,你来验。请求头为 app_id / nonce / timestamp / signature 不验签意味着任何人只要知道你的回调地址就能伪造事件,请不要跳过这一步

应答要求

  • HTTP 状态码必须为 200
  • 响应体必须是标准 JSON:{"code": 0}
  • 我们的请求超时为 10 秒,你的处理逻辑要在此之内返回(重活请异步化)
返回非 200、返回体不是 JSON、或 code 非 0,都会被记为一次失败。

事件一览

user_enter — 用户进入会议

role0 普通成员、1 主持人、2 联席主持人。 同一个 user_id 在多端进会时,每一端都会触发一次。

user_exit — 用户离开会议

user_enter 多两个字段:
  • reason1 主动离开、2 被踢、3 被顶号、4 心跳超时、5 会议销毁、6 身份变成观众
  • online 是该用户离开会中的在线人数,0 意味着人走空了
online == 0 判断「会议实际空了」比自己维护计数可靠。

meeting_status_change — 会议状态变化

状态取值:1 未开始、2 进行中、3 已结束。带上 from_status 是为了让你能区分 「正常开始」(1→2)与「异常重开」这类情况。

mcu_status_change — 录制任务状态变化

  • task_type 按位组合,取值见云录制与直播接入指南
  • task_status0 待开始、1 进行中、2 待结束、3 异常结束、4 正常结束
  • err_desc 只在 task_status=3 时有内容
  • record_count / total_duration / total_size 是本次录制产出的文件数、总时长(秒)、总字节
02 是过渡状态,业务侧一般只需要关心 1(开始了)、3(出错了)、4(结束了)。 任务结束时这条事件里的 record_count 往往还是 0:录像文件要等任务结束后才开始转码上传。 全部文件传完后会再补发一条本事件,那一条的计数才完整。

mcu_record_done — 一个录像文件已就绪

这个事件才是取回放地址的正确时机。 任务 task_status 变成 4(正常结束)时文件 往往还在转码上传,此时取地址可能拿不到东西。 一场会议的一次录制会产出多个文件,本事件按文件推送。 录制超过分片上限(默认 1 小时) 会按时长切段,录制中途中断后被续上也会另起一段。因此:
  • 取播放地址用 record_id,不是 task_id,见单个录像文件的点播地址
  • seq 从 1 开始,按它排序即播放顺序;offset_ms 是相对整场录制开始的偏移(毫秒),做连播用
  • reason1 按时长切段、2 中断后续录(与上一片之间有时间空洞)、3 结束收尾、0 未知
  • is_lasttrue 表示本次录制的文件已全部就绪
duration 是本片时长(秒),vod_size 是本片字节数。
想一次拿到一场会议的全部可播地址,用 一场会议全部录像的点播地址, 它会把每一段都返回,按分片序号排好。

mcu_alarm — 录制任务异常

gw 是任务所在的网关节点,排查时告诉我们这个值能快很多。注意告警不代表任务已终止 —— 以 mcu_status_changetask_status 为准。

幂等与重试

网络抖动可能导致同一事件送达多次,业务侧请按 event + 业务主键(meeting_idtask_iduser_id)做幂等。不要用 time 去重 —— 同一秒内可以有多个同类事件。