tencent cloud

实时音视频

文档实时音视频视频通话 SDK服务端 API第三方回调录制相关录制状态变更之后回调

录制状态变更之后回调

下载
聚焦模式
字号
最后更新时间： 2026-06-05 11:15:57

功能说明

App 后台可以通过该回调实时监控云端录制任务的状态变化。

注意事项

要启用回调，必须通过 REST API 配置回调 URL，并打开本条回调协议对应的开关，配置方法详见 设置回调配置 文档。
回调的方向是 TRTC 后台向 App 后台发起 HTTP POST 请求。
App 后台在收到回调请求之后，务必校验请求 URL 中的参数 SDKAppID 是否是自己的 SDKAppID。

可能触发该回调的场景

云端录制任务状态变更。

回调发生时机

云端录制任务状态发生变更之后。

接口说明

请求 URL 示例

以下示例中 App 配置的回调 URL 为 https://www.example.com。
示例：
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

请求参数说明

参数
说明
https
请求协议为 HTTPS，请求方式为 POST。
www.example.com
回调 URL。
SdkAppid
创建应用时在 TRTC 控制台分配的 SDKAppID
CallbackCommand
固定为 Call.CallbackAfterRecordChanged 。
contenttype
固定值为 json。
ClientIP
客户端 IP，格式如：127.0.0.1。
OptPlatform
客户端平台，取值参见 第三方回调简介 中 OptPlatform 的参数含义。

请求包示例及参数说明

{
    "CallId": "f6273604-3806-4abb-bc7e-090cd9208ee6",
    "Callback": {
        "EventGroupId": 3,
        "EventType": 301,
        "CallbackTs": 1774425607091,
        "EventInfo": {
            "RoomId": "1280586498",
            "EventTs": 1774425607,
            "UserId": "callkit_1500099430_record_1280586498",
            "TaskId": "-nHuqHlU7islZCDCjMne7HY2TJoU1NbbDkHjVoK-yqHu8ZWQndibQJtEhvB6ShqolkmNmnxz7AE.",
            "Payload": {
                "Status": 0
            },
            "EventMsTs": 1774425607077
        },
        "KitType": 2
    },
    "CallbackCommand": "Call.CallbackAfterRecordChanged",
    "EventTime": 1774425607149
}

事件回调消息的 body 中包含以下字段：

字段名
类型
含义
CallbackCommand
String
回调命令字。
EventTime
Number
事件触发的毫秒级别时间戳。
CallId
String
通话 ID。
Callback
JsonObject
具体事件信息。

事件类型 EventType 说明：

字段名
类型
含义
EVENT_TYPE_CLOUD_RECORDING_RECORDER_START
301
云端录制模块启动。
EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT
311
云端录制 VOD 录制任务上传媒体资源完成，在选择云点播时和通过控制台自动录制存储至 cos 时回调（录制文件结束后携带点播索引信息，请订阅此类型回调事件）。
EVENT_TYPE_CLOUD_RECORDING_VOD_STOP
312
云端录制 VOD 录制任务结束，仅在选择云点播时回调。

事件信息说明：

字段名
类型
含义
RoomId
String/Number
房间名（类型与客户端房间号类型一致）。
EventTs
Number
事件发生的 Unix 时间戳，单位为秒 (不建议使用该字段，建议使用 EventMsTs)。
EventMsTs
Number
事件发生的 Unix 时间戳，单位为毫秒。
UserId
String
录制机器人的用户 ID。
TaskId
String
录制 ID，一次云端录制任务唯一的 ID。
Payload
JsonObject
根据不同事件类型定义不同。

事件类型为301
（EVENT_TYPE_CLOUD_RECORDING_RECORDER_START）时 Payload 的定义：
字段名
类型
含义
Status
Number
0：代表录制模块启动成功。
1：代表录制模块启动失败。
{
    "EventGroupId": 3,
    "EventType": 301,
    "CallbackTs": 1622186275913,
    "EventInfo": {
        "RoomId": "635055",
        "EventTs": "1622186275",
        "EventMsTs": 1622186275757,
        "UserId": "user1",
        "TaskId": "-m9-bVVU7id***K-m928oZWQndiborbEWH3zY-lIXlprc-gQvQE",
        "Payload": {
            "Status": 0
        }
    }
}

事件类型为311
（EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT）时 Payload 的定义：
字段名
类型
含义
Status
Number
0：代表本录制文件正常上传至点播平台。
1：代表本录制文件滞留在服务器或者备份存储上。
2：代表本录制文件上传点播任务异常。
UserId
String
本录制文件对应的用户 ID（当录制模式为合流模式时，此字段为空）。
TrackType
String
audio 音频 / video 纯视频 / audio_video 音视频。
MediaId
String
主辅流标识，main 代表主流（摄像头），aux 代表辅流（屏幕分享），mix 代表混流录制。
FileId
String
本录制文件在点播平台的唯一 ID。
VideoUrl
String
本录制文件在点播平台的播放地址。
CacheFile
String
本录制文件对应的 MP4/HLS 文件名。
StartTimeStamp
Number
本录制文件开始的 UNIX 时间戳（毫秒）。
EndTimeStamp
Number
本录制文件结束的 UNIX 时间戳（毫秒）。
Errmsg
String
status 不为0时，对应的错误信息。
上传成功的回调：
{
  "EventGroupId": 3,
  "EventType": 311,
  "CallbackTs": 1622191965320,
  "EventInfo": {
    "RoomId": "20015",
    "EventTs": 1622191965,
    "EventMsTs": 1622186275757,
    "UserId": "user1",
    "TaskId": "-m9-bVVU7id***K-m928oZWQndiborbEWH3zY-lIXlprc-gQvQE",
    "Payload": {
      "Status": 0,
      "TencentVod": {
        "UserId": "user2",
        "TrackType": "audio_video",
        "MediaId": "main",
        "FileId": "5145403691953718116",
        "VideoUrl": "http://example/f0.mp4",
        "CacheFile": "1400704311_635055__UserId_s_dHVmdGpk__UserId_e_main.mp4",
        "StartTimeStamp": 1622186279153,
        "EndTimeStamp": 1622186282153
      }
    }
  }
}
上传失败的回调：
{
  "EventGroupId": 3,
  "EventType": 311,
  "CallbackTs": 1622191965320,
  "EventInfo": {
    "RoomId": "20015",
    "EventTs": 1622191965,
    "EventMsTs": 1622186275757,
    "UserId": "user1",
    "TaskId": "-m9-bVVU7id***K-m928oZWQndiborbEWH3zY-lIXlprc-gQvQE",
    "Payload": {
      "Status": 1,
      "Errmsg": "vod service stop",
      "TencentVod": {
        "UserId": "user1",
        "TrackType": "audio_video",
        "CacheFile": "-m9-bVVU7id***K-m928oZWQndiborbEWH3zY-lIXlprc-gQvQE"
      }
    }
  }
}
说明：
录制完成收到311回调后到文件上传完成，根据您本次录制文件的大小不同可能需等待30s - 3min。

事件类型为312
（EVENT_TYPE_CLOUD_RECORDING_VOD_STOP）时 Payload 的定义：
字段名
类型
含义
Status
Number
0：代表本次上传 VOD 任务已经正常退出。
1：代表本次上传 VOD 任务异常退出。
{
  "EventGroupId": 3,
  "EventType": 312,
  "CallbackTs": 1622191965320,
  "EventInfo": {
    "RoomId": "20015",
    "EventTs": 1622191965,
    "EventMsTs": 1622186275757,
    "UserId": "user1",
    "TaskId": "-m9-bVVU7id***K-m928oZWQndiborbEWH3zY-lIXlprc-gQvQE",
    "Payload": {
      "Status": 0
    }
  }
}

应答包示例

App 后台同步数据后，发送回调应答包。
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0
}

应答包字段说明

字段
类型
属性
说明
ActionStatus
String
必填
请求处理的结果，OK 表示处理成功，FAIL 表示失败。
ErrorInfo
String
必填
错误信息，处理成功时为空字符串。
ErrorCode
Integer
必填
错误码，0 表示忽略应答结果，继续后续流程。

参考

第三方回调简介
上一篇: 通话成员状态变更后回调下一篇: 通话状态回调

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈