Status Callback

RC provides HTTP callbacks for recording status updates when cloud recording starts, generates file segments, completes recording, or uploads files. You can obtain the mapping between recording metadata and filenames/final URLs. If you've enabled the Cloud Recording service and configured a publicly accessible callback URL, RC will notify your configured server address in real-time about recording status changes.

Configure your callback URL in the Console's Cloud Recording page. Changes take effect within 15 minutes.

Callback Method

POST: <your-receiving-server-url>

Data format: application/json

The callback address <your-receiving-server-url> is the receiving endpoint you configured in the Console for your App Key and service. Ensure this address is accessible. If your network has IP restrictions, configure the IP allowlist to receive server callbacks properly.

To verify data authenticity and ensure requests originate from RC Server, each request includes a signature. See Server Callback for signature rules.

Common Callback Fields

The table below describes common fields in HTTP callback requests (JSON objects) for different cloud recording statuses:

Field	Type	Description
timestamp	Number	Timestamp in milliseconds.
type	Number	Callback event type: 1: Recording start; 2: File segment; 3: Recording end; 4: File upload
appKey	String	Current App Key.
recordId	String	Unique recording task ID. File segments can be correlated using this ID.
roomId	String	Room ID.
sessionId	String	Session ID, unique identifier for each call. Obtain via RC server callback—see Room Status Sync.
userId	String	User ID. Empty for Mix recording mode.
mode	Number	Recording mode: 0: AV single mode; 1: Video-only single mode; 2: Audio-only single mode; 3: AV mix mode; 4: Video-only mix mode; 5: Audio-only mix mode; 6: Single-user AV mix mode. See Recording Mode Details in Configure Cloud Recording.
extra	String	Custom field containing the extra value passed during manual recording.
code	Number	Status code. 200 indicates success.
errorMessage	String	Error message.

See below for mode-specific callback fields.

Recording Start Callback

RC notifies you about recording mode, configuration, and file format when recording begins.

Field	Type	Description
config.trigger	Number	Recording trigger mode: 1 for automatic start
config.mixLayout	Number	Mix mode layout: 2 Floating (default) or 3 Adaptive
config.slicesMin	Number	File segment duration (minutes)
config.audioFormat	String	Configured audio format
config.videoFormat	String	Configured video format
output.fileName	String	Temporary filename. See Naming Rules.
output.audioSample	Number	Audio sample rate (e.g., 48000). Empty if no audio.
output.videoResoulation	String	Video resolution (e.g., 640x480). Empty if no video.

Callback Example

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":1,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "config":{
        "trigger":0,
        "mixLayout":2,
        "slicesMin":30,
        "audioFormat":"aac",
        "videoFormat":"mp4"
    },
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "audioSample":48000,
        "videoResoulation":"640x480"
    },
    "code": 200,
    "errorMessage": "Success"
}

File Segment Callback

When recording duration exceeds segment length, cached AV data is packaged into a complete file and uploaded.

Field	Type	Description
output.fileName	String	Segment filename. See Naming Rules.
output.fileSize	Number	Segment file size.

Callback Example

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":2,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileSize":333
    },
    "code": 200,
    "errorMessage": "Success"
}

Recording End Callback

RC notifies you when recording completes.

Field	Type	Description
output.fileName	String	Final filename. See Naming Rules.
output.fileSize	Number	Final file size.

Callback Example

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":3,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileSize":333
    },
    "code": 200,
    "errorMessage": "Success"
}

File Upload Callback

RC automatically uploads recordings to your configured third-party storage and notifies you of success/failure.

Field	Type	Description
output.fileName	String	Uploaded filename. See Naming Rules.
output.fileUrl	String	URL of the file in third-party storage.

Callback Example

POST /any-url-path HTTP/1.1
Host: your.app.server
Content-Type: application/json

{
    "timestamp":1530027865231,
    "type":4,
    "appKey":"your_appkey",
    "recordId":"8329208b99410743dcfeb80548e2c0ec",
    "roomId":"111",
    "sessionId":"lSA2G6CUf9A-6nnoNwXCx8",
    "userId":"222",
    "mode":1,
    "extra":"extra_string",
    "output":{
        "fileName":"lSA2G6CUf9A-6nnoNwXCx8_111_222_1530027865231.mp4",
        "fileUrl":"http://oss/record/XXXXXXXX.mp4?abc"
    },
    "code": 200,
    "errorMessage": "Success"
}

Naming Rules

Note

The following rules are for reference only. Parsing specific fields is not recommended.

Recording Mode	Naming Pattern
Mix mode	SessionId_RoomId_Timestamp.FileFormat Example: 1K6-Q3uj6w7cfbGSq0ahA9_1775_1577616009233.mkv
Single mode	SessionId_RoomId_UserId_StreamTag_Timestamp.FileFormat Example: 1K6-Q3uj6w7cfbGSq0ahA9_1775_123456_RongCloudRTC_1577616009233.mkv
Single-user AV mix mode	SessionId_RoomId_UserId_Timestamp.FileFormat Example: 1K6-Q3uj6w7cfbGSq0ahA9_1775_123456_1577616009233.mkv

Field Descriptions

Field	Description
SessionId	Current call session ID. Obtain from room object (RTCLib) or call session (CallLib).
RoomId	Room ID where the call occurs. For RTCLib: Passed when joining a room. For CallLib: Use getCallId.
UserId	User ID of the participant.
StreamTag	Tag set for custom video or screen-sharing streams.
Timestamp	Unix timestamp in milliseconds.

Responding to Callbacks

Your server must return 200 OK upon receiving HTTP callbacks.

Callback Status Codes:

• If third-party storage fails, recordings are temporarily stored on RC servers and retried every 10s for up to 24 hours.
• Upon failure, check your storage service status. If issues persist, configure a new storage unit within 15 minutes to minimize data loss.