tencent cloud

Tencent Real-Time Communication

문서Tencent Real-Time CommunicationCallServer APIsThird-Party CallbackRecord RelatedWebhook After Record Changed

Webhook After Record Changed

다운로드
포커스 모드
폰트 크기
마지막 업데이트 시간: 2026-06-05 11:15:08

Feature Description

Use this callback to monitor real-time status changes for cloud recording tasks on your app backend.

Notes

To enable the callback, configure the callback URL using the REST API and activate the corresponding callback protocol switch. For setup instructions, see the Setting Callback Configuration.
The callback is sent from the TRTC backend to your app backend as an HTTP POST request.
After receiving a callback request, your app backend must verify that the SDKAppID parameter in the request URL matches your own SDKAppID.

Scenarios That May Trigger This Callback

Status changes for cloud recording tasks

Callback Trigger Timing

After the status of a cloud recording task changes.

API Description

Example Request URL

The example below shows the App's configured callback URL as https://www.example.com.
Example:
https://www.example.com?SdkAppid=$SDKAppID&CallbackCommand=$CallbackCommand&contenttype=json&ClientIP=$ClientIP&OptPlatform=$OptPlatform

Request Parameter Description

Parameter
Description
https
The request protocol is HTTPS. The request method is POST.
www.example.com
Callback URL.
SdkAppid
SDKAppID assigned when you create your application in the TRTC Console.
CallbackCommand
Fixed value: Call.CallbackAfterRecordChanged.
contenttype
Fixed value: json.
ClientIP
Client IP address. Example format: 127.0.0.1.
OptPlatform
Client platform. For possible values, see the OptPlatform parameter description in Third-Party Callback Overview.

Example Request Payload and Parameter Description

{
    "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
}

Event Callback Payload Fields

Field Name
Type
Description
CallbackCommand
String
Callback command.
EventTime
Number
Timestamp (milliseconds) when event triggered.
CallId
String
Call ID.
Callback
JsonObject
Detailed event information.

EventType Description

Field Name
Type
Description
EVENT_TYPE_CLOUD_RECORDING_RECORDER_START
301
Cloud recording module started.
EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT
311
Cloud recording VOD task finished uploading media resources. Callback occurs when Cloud VOD is selected or when auto-recording to COS is enabled via the console (callback includes VOD index info after the recording file ends; subscribe to this event type for notifications).
EVENT_TYPE_CLOUD_RECORDING_VOD_STOP
312
Cloud recording VOD task ended. Callback occurs only when Cloud VOD is selected.

Event Information Description

Field Name
Type
Description
RoomId
String/Number
Room name (type matches client room number type)
EventTs
Number
Unix timestamp (seconds) for event occurrence (not recommended; use EventMsTs instead)
EventMsTs
Number
Unix timestamp (milliseconds) for event occurrence
UserId
String
Recording Bot user ID
TaskId
String
Recording ID; unique for each cloud recording task
Payload
JsonObject
Payload structure varies by event type
For
EventType 301
(EVENT_TYPE_CLOUD_RECORDING_RECORDER_START), Payload definition:
Field Name
Type
Description
Status
Number
0: Recording module started successfully.
1: Failed to start recording module.
{
    "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
        }
    }
}
For
EventType 311
(EVENT_TYPE_CLOUD_RECORDING_VOD_COMMIT), Payload definition:
Field Name
Type
Description
Status
Number
0: Recording file uploaded to VOD platform successfully.
1: Recording file remains on server or backup storage.
2: Recording file upload to VOD failed.
UserId
String
User ID associated with the recording file (empty if recording mode is mixed stream).
TrackType
String
audio: audio only / video: video only / audio_video: audio and video.
MediaId
String
Stream identifier: main for main stream (camera), aux for substream (screen sharing), mix for mixed stream recording.
FileId
String
Unique ID of the recording file on the VOD platform.
VideoUrl
String
Playback URL of the recording file on the VOD platform.
CacheFile
String
MP4/HLS file name corresponding to the recording file.
StartTimeStamp
Number
UNIX timestamp (milliseconds) when the recording file started.
EndTimeStamp
Number
UNIX timestamp (milliseconds) when the recording file ended.
Errmsg
String
Error message if status is not 0.
Callback for successful upload:
{
  "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
      }
    }
  }
}
Callback for failed upload:
{
  "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"
      }
    }
  }
}
Note:
After receiving the 311 callback for recording completion, the upload time for the recording file may vary based on file size, typically ranging from 30 seconds to 3 minutes.
For
EventType 312
(EVENT_TYPE_CLOUD_RECORDING_VOD_STOP), Payload definition:
Field Name
Type
Description
Status
Number
0: VOD upload task exited normally.
1: VOD upload task exited abnormally.
{
  "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
    }
  }
}

Example Response Payload

After synchronizing the data, your app backend should send the following callback response payload:
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0
}

Response Payload Field Description

Field
Type
Attribute
Description
ActionStatus
String
Required
Result of request processing: OK for success, FAIL for failure.
ErrorInfo
String
Required
Error message; empty string if processing is successful.
ErrorCode
Integer
Required
Error code; 0 means ignore the response and continue processing.

Reference

Third-Party Callback Overview
이전 주제: Callback after Member Changed다음 주제: Call Status Callback

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백