Status Callback

RC's cloud screenshot service supports real-time notification of screenshot status changes to your server.

You can configure an HTTP callback URL in the Console's cloud screenshot section. Changes take effect within 15 minutes after configuration.

Callback URL example: http(s)://your.app.server/any-url-path

Once configured, all screenshot status changes for rooms in your app will trigger real-time HTTP callbacks to your server.

Usage notes:

Important

• RTC service and cloud screenshot service must be activated.
• Your callback URL must be publicly accessible.

Callback Method

POST: <your-receiving-server-url>

Data format: application/json

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

To verify data authenticity and ensure the caller is RC Server, each request includes a signature. See Server Callback for signature rules.

Common Callback Fields

Field	Type	Description
type	Number	1: Screenshot start; 3: Screenshot end; 4: File upload
sessionId	String	Session ID
extra	String	Extended field, passed through
appKey	String	Your AppKey
roomId	String	Room ID
imageId	String	Screenshot session ID
code	Number	Status code
errorMessage	String	Status description

Screenshot Start Callback

The cloud screenshot service triggers this callback when a screenshot task begins, including mode, configuration, and file format details.

Field details:

Field	Type	Description
config.trigger	String	Manual or automatic trigger
config.slicesSec	String	Screenshot interval
config.renderMode	Number	Screenshot mode
config.picResolution	String	Screenshot resolution

Request Example

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

{
   "timestamp": 1530027865231,
   "type": 1,
   "appKey": "e0x9wycfx7flq",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "extra":"", // Extended field
   "config": {
       "trigger": 0,
       "slicesSec": 30,
       "renderMode": 1,
       "picResolution": "640x480"
   },
   "code": 200,
   "errorMessage": "Success"
}

Screenshot End Callback

Triggered when screenshotting completes, with the same fields as the start callback.

Request Example

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

{
   "timestamp": 1530027865231,
   "type": 3,
   "appKey": "e0x9wycfx7flq",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "extra":"", // Extended field
   "config": {
       "trigger": 0,
       "slicesSec": 30,
       "renderMode": 1,
       "picResolution": "640x480"
   },
   "code": 200,
   "errorMessage": "Success"
}

File Upload Callback

Triggered when screenshots are uploaded to your third-party storage, whether successful or failed.

Field details:

Field	Type	Description
output.fileName	String	Cached filename (see naming rules below)
output.fileUrl	String	URL of the uploaded file in third-party storage

Request Example

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

{
   "timestamp": 1530027865231,
   "type": 4,
   "appKey": "e0x9wycfx7flq",
   "imageId": "SJGOSOIOAIJFOJAOJOE",
   "sessionId": "lSA2G6CUf9A-6nnoNwXCx8",
   "roomId": "111",
   "tag":"",
   "extra":"", // Extended field
   "output": {
       "fileName": "1.jpg",
       "fileUrl": "http://oss/record/1.jpg",
       "fileState": "10000", // string, backward compatible
       "fileMsg": "ok"
   },
   "code": 200,  // Returns 200 if output.fileState is 10000; otherwise matches output.fileState
   "errorMessage": "Success"    // Same as output.fileMsg
}

Screenshot File Naming Rules

Screenshot Mode	File Format (jpg)
Video single mode	Sessionid_RoomId_Userid_streamId_timestamp.fileFormat Example: --05oNAPhi9CtbD7FzeVI7_2972_1860099998888_tag98_11128382862.jpg

Field in Filename	Description
SessionId	Current call session ID. Obtainable from the room object (RTCLib) or call session (CallLib).
RoomId	Room ID where the call occurs. For RTCLib, it's the parameter when joining a room; for CallLib, use getCallId.
UserId	User ID in the call.
StreamId	Stream ID of the published video.
Timestamp	Unix timestamp in milliseconds.

Note

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

Responding to Callbacks

Return 200 OK to acknowledge successful receipt.

Callback status notes:

• If third-party storage fails, screenshot files are temporarily stored on RC servers and retried every 10s. Files are retained for up to 24 hours before being cleared.
• Upon failure, check your storage service status. If issues persist, configure a new storage unit (changes take 15 minutes to apply).