Agora Cloud Recording RESTful API Callback Service

Agora provides the Message Notification Service. You can set up an HTTP/HTTPS server to receive the event notifications of Agora Cloud Recording. When an event occurs, the Agora Cloud Recording service notifies the Message Notification Service, and then the Message Notification Service notifies your server of that event through an HTTP/HTTPS request.

Agora message notification service

Contact us to configure and enable the callback service. See Message Notification Service for details.

Callback information

After you enable the callback service, when a specified event occurs, the Agora notification center sends an HTTP/HTTPS request as a callback. The request body provides the main information of the callback in a JSON object. The JSON object contains different fields for different events.

The following is an example that shows the fields in the request body.

• The fields in the red rectangle are the common fields of all the callback events. For details, see Notification callback format.
• The fields in the blue rectangle are the common fields in payload of all the cloud recording events. For details, see Fields in payload.
• The values of eventType, serviceType, and details depend on the event. For details, see Callback events.

Fields in payload

payload is a JSON object, which is the main body of the notification. payload in each type of event notification includes the following fields:

• cname: String. The name of the channel to be recorded.
• uid: String. The user ID of the recording client.
• sid: String. The recording ID. The unique identifier of each recording.
• sequence: Number. The serial number of the notifications, starting from 0. You can use this parameter to identify notifications that are random, lost, or resent.
• sendts: Number. The time (UTC) when the event happens. Unix timestamp in ms.
• serviceType: Number. The type of Agora service.
  • 0: The cloud recording service.
  • 1: The recorder module.
  • 2: The uploader module.
  • 4: The extension services.
  • 6: The web page recording module.
  • 8: The download module.
• details: JSON. The details of the callback events are described as follows. The message notification service may add new fields in details in the future. To ensure backward compatibility, the service will not change the data format of existing fields.

Callback events

The related fields of the Agora Cloud Recording callback events are listed below:

1 cloud_recording_error

eventType 1 indicates that an error occurs during the recording. details includes the following fields:

• msgName: String. The name of the message, "cloud_recording_error".

• module: Number. The module in which the error occurs.

  • 0: The recorder
  • 1: The uploader
  • 2: The Agora Cloud Recording Service
  • 6：The Agora Web Page Recording Service

• errorLevel: Number. The error level.

  • 1: Debug
  • 2: Minor
  • 3: Medium
  • 4: Major
  • 5: Fatal. A fatal error may cause the recording to exit. If you receive a message of this level, call query to check the current status and process the error according to the error notifications.

• errorCode: Number. The error code.

  • If the error occurs in the recorder module (0), see common errors.
  • If the error occurs in the uploader (1), see upload error code.
  • If the error occurs in the Agora Cloud Recording Service (2), see cloud recording service error code.
  • If the error occurs in the other modules, see common errors.
    If you do not find any error code in the above-mentioned pages, contact our technical support.

• stat: Number. The event status. 0 indicates normal status; other values indicate abnormal status.

• errorMsg: String. The detailed description of the error.

2 cloud_recording_warning

eventType 2 indicates that a warning occurs during the recording. details includes the following fields:

• msgName: String. The message name, cloud_recording_warning.
• module: Number. The name of the module where the warning occurs.
  • 0: The recorder.
  • 1: The uploader.
• warnCode: Number. The warning code.
  • If the warning occurs in the recorder, see warning code.
  • If the warning occurs in the uploader, see upload warning code.

3 cloud_recording_status_update

eventType 3 indicates that the method call fails because it does not match the status of the cloud recording service. For example, the method call of start fails if the service has already started. details includes the following fields:

• msgName: String. The message name, cloud_recording_status_update.
• status: Number. The status of the cloud recording service. See Status codes for the Agora Cloud Recording service for details.
• recordingMode: Number. The recording mode:
  • 0: Individual recording mode
  • 1: Composite recording mode
• fileList: String. The name of the M3U8 index file generated by the service.

4 cloud_recording_file_infos

eventType 4 indicates that an M3U8 playlist file is generated and uploaded. During a recording, the recording service repeatedly uploads and overwrites the M3U8 file, but this event is triggered the first time the M3U8 file is generated and uploaded.

details includes the following fields:

• msgName: String. The message name, cloud_recording_file_infos.
• fileList: String. The name of the M3U8 file.

11 session_exit

eventType 11 indicates that the cloud recording service has ended its tasks and exited. details includes the following fields:

• msgName: String. The message name, session_exit.
• exitStatus: Number. The exit status.
  • 0: A normal exit, indicating that the recording service exits after the recording ends and the recorded files are uploaded.
  • 1: An abnormal exit. An abnormal exist occurs when, for example, a parameter is incorrectly set.

12 session_failover

eventType 12 indicates that the cloud recording service has enabled the high availability mechanism, where the fault processing center automatically switches to a new server within 90 seconds to resume the service. details includes the following fields:

• msgName: String. The message name, session_failover.
• newUid: Number. A randomly-generated recording user ID. After the high availability mechanism is enabled and the service is switched to a new server, the service rejoins the channel with a randomly-generated recording user ID, abandoning the old one.

30 uploader_started

eventType 30 indicates that the upload service starts, and details includes the following fields:

• msgName: String. The message name, uploader_started.
• status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.

31 uploaded

eventType 31 indicates that all the recorded files are uploaded to the specified third-party cloud storage, and details includes the following fields:

• msgName: String. The message name, uploaded.
• status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.
• fileList: JSONArray. An array that contains detailed information of each recorded file.
  • fileName: String. The name of the M3U8 file or MP4 file.
  • trackType: String. The type of the recorded file.
    • "audio": Audio file.
    • "video": Video file (no audio).
    • "audio_and_video": Video file (with audio).
  • uid: String. The user ID. The user whose audio or video is recorded in the file. In composite recording mode, uid is "0".
  • mixedAllUser: Boolean. Whether the audio and video of all users are combined into a single file.
    • true: All users are recorded in a single file.
    • false: Each user is recorded separately.
  • isPlayable: Boolean. Whether the file can be played online.
    • true: The file can be played online.
    • false: The file cannot be played online.
  • sliceStartTime: Number. The Unix time (ms) when the recording starts.

Example

{
  "msgName": "uploaded",
  "fileList": [
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio",
      "uid": "57297",
      "mixedAllUser": false,
      "isPlayable": true,
      "sliceStartTime": 1619172871089
    },
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio",
      "uid": "10230",
      "mixedAllUser": false,
      "isPlayable": true,
      "sliceStartTime": 1619172871099
    }
  ],
  "status": 0
}

{
  "msgName": "uploaded",
  "fileList": [
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619170461821
    }
  ],
  "status": 0
}

{
  "msgName": "uploaded",
  "fileList": [
    {
      "fileName": "xxx.mp4",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619172632080
    },
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619172632080
    }
  ],
  "status": 0
}

{
  "msgName": "uploaded",
  "status": 0
}

32 backuped

eventType 32 indicates that all the recorded files are uploaded, but at least one of them is uploaded to Agora Cloud Backup. Agora Cloud Backup automatically uploads the files to the specified third-party cloud storage. details includes the following fields:

• msgName: String. The message name, backuped.
• status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.
• fileList: JSONArray. An array that contains detailed information of each recorded file.
  • fileName: String. The name of the M3U8 file or MP4 file.
  • trackType: String. The type of the recorded file.
    • "audio": Audio file.
    • "video": Video file (no audio).
    • "audio_and_video": Video file (with audio).
  • uid: String. The user ID. The user whose audio or video is recorded in the file. In composite recording mode, uid is "0".
  • mixedAllUser: Boolean. Whether the audio and video of all users are combined into a single file.
    • true: All users are recorded in a single file.
    • false: Each user is recorded separately.
  • isPlayable: Boolean. Whether the file can be played online.
    • true: The file can be played online.
    • false: The file cannot be played online.
  • sliceStartTime: Number. The Unix time (ms) when the recording starts.

Example

{
  "msgName": "backuped",
  "fileList": [
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio",
      "uid": "57297",
      "mixedAllUser": false,
      "isPlayable": true,
      "sliceStartTime": 1619172871089
    },
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio",
      "uid": "10230",
      "mixedAllUser": false,
      "isPlayable": true,
      "sliceStartTime": 1619172871099
    }
  ],
  "status": 0
}

{
  "msgName": "backuped",
  "fileList": [
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619170461821
    }
  ],
  "status": 0
}

{
  "msgName": "backuped",
  "fileList": [
    {
      "fileName": "xxx.mp4",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619172632080
    },
    {
      "fileName": "xxx.m3u8",
      "trackType": "audio_and_video",
      "uid": "0",
      "mixedAllUser": true,
      "isPlayable": true,
      "sliceStartTime": 1619172632080
    }
  ],
  "status": 0
}

{
  "msgName": "backuped",
  "status": 0
}

33 uploading_progress

eventType 33 indicates the current upload progress. The Agora server notifies you of the upload progress once every minute after the recording starts. details includes the following fields:

• msgName: String. The message name, uploading_progress.
• progress: Number. An ever-increasing number between 0 and 10,000, equal to the ratio of the number of the uploaded files to the number of the recorded files multiplied by 10,000. After the recording service exits and when the number reaches 10,000, the upload completes.

40 recorder_started

eventType 40 indicates that the recording service starts, and details includes the following fields:

• msgName: String. The message name, recorder_started.
• status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.

41 recorder_leave

eventType 41 indicates that the recorder leaves the channel, and details includes the following fields:

• msgName: String. The message name, recorder_leave.
• leaveCode: Number. The leave code. You can perform a bitwise AND operation on the code and each enum value, and those with non-zero results are the reason for the exit. For example, if you perform a bit-by-bit AND operation on code 6 (binary 110) and each enum value, only LEAVE_CODE_SIG (binary 10) and LEAVE_CODE_NO_USERS (binary 100) get a non-zero result. The reasons for exiting, in this case, include a timeout and a signal triggering the exit.

  Enumerator
  LEAVE_CODE_INIT	0: The initialization fails.
  LEAVE_CODE_SIG	2 (binary 10): The AgoraCoreService process receives the SIGINT signal.
  LEAVE_CODE_NO_USERS	4 (binary 100): The recording server automatically leaves the channel and stops recording because the channel has no user.
  LEAVE_CODE_TIMER_CATCH	8 (binary 1000): Ignore it.
  LEAVE_CODE_CLIENT_LEAVE	16 (binary 10000): The recording server calls the leaveChannel method to leave the channel.

42 recorder_slice_start

eventType 42 indicates that the recording service syncs the information of the recorded files, and details includes the following fields:

• msgName: String. The message name, recorder_slice_start.
• startUtcMs：Number. The time (ms) in UTC when the recording starts (the starting time of the first slice file).
• discontinueUtcMs：Number. In most cases, this field is the same as startUtcMs. When the recording is interrupted, the Agora Cloud Recording service automatically resumes the recording and triggers this event. In this case, the value of this field is the time (ms) in UTC when the last slice file stops.
• mixedAllUser: Boolean. Whether the audio and video of all users are mixed into a single file.
  • true: All users are recorded in a single file.
  • false: Each user is recorded separately.
• streamUid: String. User ID. The user whose audio or video is recorded in the file. In composite mode, streamUid is 0.
• trackType: String. Type of the recorded file.
  • "audio": Audio file.
  • "video": Video file (no audio).
  • "audio_and_video": Video file (with audio).

For example, you start a recording session and get this event notification in which startUtcMs is the starting time of slice file 1. Then, the recording session continues and records slice file 2 to slice file N, during which the recording service does not send this notification again. If an error occurs when recording slice file N + 1, you lose this file and the recording session stops. Agora Cloud Recording automatically resumes the recording and triggers this event again. In the event notification, startUtcMs is the time when slice file N + 2 starts, and discontinueUtcMs is the time when slice file N stops.

43 recorder_audio_stream_state_changed

eventType 43 indicates that the state of the audio stream has changed, and details includes the following fields:

• msgName: String. The message name, recorder_audio_stream_state_changed.
• streamUid: String. The ID of the user whose audio is being recorded. In composite recording mode, streamUid can be 0, which represents the combined stream of all or the specified user IDs.
• state : Number. Whether Agora Cloud Recording is receiving the audio stream.
  • 0: Agora Cloud Recording is receiving the audio stream.
  • 1: Agora Cloud Recording is not receiving the audio stream.
• UtcMs: Number. The UTC time (ms) when the state of the audio stream changes.

44 recorder_video_stream_state_changed

eventType 44 indicates that the state of the video stream has changed, and details includes the following fields:

• msgName: String. The message name, recorder_video_stream_state_changed.
• streamUid: String. The ID of the user whose video is being recorded. In composite recording mode, streamUid can be 0, which represents the combined stream of all or the specified user IDs.
• state: Number. Whether Agora Cloud Recording is receiving the video stream.
  • 0: Agora Cloud Recording is receiving the video stream.
  • 1: Agora Cloud Recording is not receiving the video stream.
• UtcMs: Number. The UTC time (ms) when the state of the video stream changes.

45 recorder_snapshot_file

eventType 45 indicates that the screenshot is captured successfully and uploaded to the third-party cloud storage. The details includes the following fields:

• msgName: String. The message name, "recorder_snapshot_file".
• fileName: String. The file name of the JPG file generated by the screenshot. The format is: "fileName": "<fileNamePrefix>/<file name>".

fileNamePrefix refers to the path of the screenshot files in the third-party cloud storage.

60 vod_started

eventType 60 indicates that the uploader for ApsaraVideo for VoD has started and successfully acquired the upload credential. details includes the following fields:

• msgName: String. The message name, "vod_started".
• aliVodInfo: JSON. The information of the video to upload.
  • videoId: String. The video ID.

61 vod_triggered

eventType 61 indicates that all recorded files have been uploaded to ApsaraVideo for VoD. details includes the following fields:

• msgName: String. The message name, "vod_triggered".

70 web_recorder_started

eventType 70 indicates that web page recording starts. details includes the following field:

• msgName: String. The message name, "web_recorder_started".
• recorderStartTime: Number. The time (UTC) when the recording starts. Unix timestamp in milliseconds.

71 web_recorder_stopped

eventType 71 indicates that web page recording stops. details includes the following field:

• msgName: String. The message name, "web_recorder_stopped".
• code: Number. The error code. If the error code is not 0, it means that the web page recording stopped abnormally.
• message: String. The error message, which indicates the reason why the recording stopped normally or abnormally.
• details: String. A specific description of the error message, which provides a more complete description of the reason why the recording stopped normally or abnormally. You can take corresponding measures based on the information.
• fileList: JSONArray. An array that contains detailed information of each recorded file.
  • fileName: String. The name of the M3U8 file or MP4 file.
  • sliceStartTime: Number. The Unix timestamp (ms) when the recording starts.

Example

{
    "msgName": "web_recorder_stopped",
    "code": 1,
    "message": "max_recording_hour",
    "details": "max recording hour is 4",
    "fileList": [
        {
            "filename": "test_p1627613634_www.m3u8",
            "sliceStartTime": 1627613641393
        },
        {
            "filename": "test_p1627613634_www_0.mp4",
            "sliceStartTime": 1627613641393
        }
    ]
}

72 web_recorder_capability_limit

eventType 72 indicates that the web page to record uses a feature that is unsupported by web page recording, and the recording service will stop immediately. details includes the following fields:

• msgName: String. The message name, "web_recorder_capability_limit".
• limitType: String. The type of the feature that causes the failure.
  • "resolution": The web page to record contains a video source with a resolution that exceeds 1280 × 720.
  • "WebGL": The web page to record uses WebGL.
  • "bandwidth"：The upstream bandwidth exceeds 10 M, or the downstream bandwidth exceeds 1 G.

73 web_recorder_reload

eventType 73 indicates a web page reload. details includes the following fields:

• msgName:String. The message name, "web_recorder_reload":
• reason:String. The reason for the page reload:
  • "audio_silence": Audio loss issue.
  • "page_load_timeout": Web page load timeout. The callback returns this field only under the following conditions: the web page load detection function is enabled, and the web page load timeout. See Web page load detection.

80 transcoder_started

eventType 80 indicates that the transcoding starts, and details includes the following field:

msgName: String. The message name, "transcoder_started".

81 transcoder_completed

eventType 81 indicates that the transcoding completes, and details includes the following fields:

• msgName: String. The message name, "transcoder_completed".

• result: String. The result of the transcoding.

  • "all_success": Successfully transcodes all files.
  • "partial_success": Fails to transcode some files.
  • "fail": The transcoding fails.

• uids: JSONArray. The array contains the transcoding result and the name of the MP4 file of a specific user ID.

  • uid: String. The corresponding user ID of the MP4 file.
  • result: String. The result of transcoding.
    • "success": Transcoding succeeds.
    • "fail": Transcoding fails.
  • fileList: JSONArray. The array contains information about the MP4 file.
  • fileName: String. The name of the MP4 file.

90 download_failed

eventType 90 indicates that the recording service fails to download the recorded files. This callback is triggered only once in the entire recording process, and details includes the following fields:

• msgName: String. The message name, "download_failed".
• vendor: Number. The name of the third-party cloud storage service, which is the same as vendor in your start request.
• region: Number. The region of the third-party cloud storage, which is the same as region set in your start request.
• bucket: String. The bucket name of the third-party cloud storage, which is the same as bucket set in your start request.
• fileName: String. The list of M3U8 or TS/WebM files that fail to be downloaded. The file names are separated by ";".

100 rtmp_publish_status

eventType 100 indicates the CDN streaming status of the web page recording. details includes the following fields:

• msgName：String. The message name, "rtmp_publish_status".
• rtmpUrl: String. The CDN address you want to the push the stream to.
• status: Number. The CDN streaming status of the web page recording, including the following options:
  • "connecting": Connecting to the CDN server.
  • "publishing": Pushing the stream to the CDN server.
  • "onhold": Pause streaming.
  • "disconnected": Failed to connect to the CDN server. Agora recommends that you change the CDN address.

1001 postpone_transcode_final_result

eventType 1001 indicates the final transcoding result, and details includes the following fields:

• msgName: String. The message name, "postpone_transcode_final_result".

• result: String. The final result of the transcoding.

  • "total_success": Successfully transcodes all files.
  • "partial_success": Fails to transcode some files.
  • "failed": The transcoding fails.

• fileList: JSONArray. The array contains information about the generated MP4 files.

• fileName: String. The name of an individual MP4 file.

Reference

Error codes related to uploading

Warning codes related to uploading

Error codes for the Agora Cloud Recording service

Status codes for the Agora Cloud Recording service