Cloud Recording RESTful API Callback Service

Jocloud-Cloud-Recording supports event notification service. You can configure an HTTP/HTTPS server to receive callbacks. When a recording event occurs, Jocloud-Cloud-Recording server notifies the callback server, and then the callback server sends an HTTP/HTTPS request to your server.

Callback message configuration

The callback function can be used when any of the following conditions is met:

Use the parameter callbackurl of startrecord to specify the HTTP/HTTPS server address to receive callback message when starting the recording task.

Callback information

After you finish the callback configuration, Cloud-Recording server sends an HTTP/HTTPS request when a recording event occurs. The content of the callback message is returned as a JSON object in the body of the POST request. Depending on the msgtype, the fields in the JSON object are different.

Request method: POST
Head:
- Content-type is application/json
Fields in the request body, for example:

{
    "msgid":"RECORD-ec0b460a0000b5794f66e14d5ab7d4ab9c166-17394cfdc6f",
    "product":1,
    "msgtype":2,
    "notifytime":1595929517000,
    "context":{
        "msgname":"recordtask_m3u8_info",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ec0b460a0000b5794f66e14d5ab7d4ab9c166",
        "filetype":"m3u8",
        "duration":9000,
        "fileaddress":"http://xxxxx.m3u8",
        "starttime":1595929495000
    }
}

The fields are common and all recording callback messages include these fields.
Common fields description:

Name	Type	Description
msgid	string	Notification ID, identifying the notification callback when the event occurs.
product	int	Product ID 1: Cloud-Recording Value range: 1
msgtype	int	Cloud-Recording event type 1: Recording task status change event 2: Recording result event Value range: 1,2
notifytime	int	The Unix timestamp of the callback request, in milliseconds.

The value of content depends on the msgtype event type.

Context information

Context is a JSON object that contains the specific content of the event.

1 recordtask_status

msgtype is 1 means recording task status change event, for example:

{
    "msgid":"RECORD-ee0b460a0000a3994f66e14d5ab7d4b902923-17394cfdb7e",
    "product":1,
    "msgtype":1,
    "notifytime":1595929516926,
    "context":{
        "msgname":"recordtask_status",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ee0b460a0000a3994f66e14d5ab7d4b902923",
        "status":2
    }
}

context fields:

Name	Type	Description
msgname	string	The name of the message, which is "recordtask_status"
appid	int	The AppID used in your project
roomid	string	ID of the room to be recorded
uid	JSON Array	User ID Note: Mixed stream recording is "0"
recordid	string	Recording ID returned after calling startrecord successfully
status	int	Record task status 0: Init status 1: Task starting 2: Task stop
endreason	int	Record task stop reason 1: Actively stop the task. 2: The stream has no data in some time and stop the task. 3: The channel has no stream for some time and stop the task. Note: This field is valid only when the recording task is stopped.

2 recordtask_m3u8_info

msgtype is 2 means recording result event, for example:

{
    "msgid":"RECORD-ec0b460a0000b5794f66e14d5ab7d4ab9c166-17394cfdc6f",
    "product":1,
    "msgtype":2,
    "notifytime":1595929517000,
    "context":{
        "msgname":"recordtask_m3u8_info",
        "appid":123123,
        "roomid":"abcabc",
        "uid":[
            "0"
        ],
        "recordid":"ec0b460a0000b5794f66e14d5ab7d4ab9c166",
        "filetype":"m3u8",
        "duration":9000,
        "fileaddress":"http://xxxxx.m3u8",
        "starttime":1595929495000
    }
}

context fields:

Name	Type	Description
msgname	string	The name of the message, which is "recordtask_m3u8_info"
appid	int	The AppID used in your project
roomid	string	ID of the room to be recorded
uid	JSON Array	User ID Note: Mixed stream recording is "0"
recordid	string	Recording ID returned after calling startrecord successfully
filetype	string	Recording file format, currently only supports "m3u8"
duration	unsigned int	The duration of the recording file, in milliseconds
fileaddress	string	The link of recording file
starttime	int	Timestamp of the earliest frame in the recording file, in milliseconds
upload_status	int	Reason when m3u8 address is empty. 0: no ts files. 2: upload timeout error. >100: HTTP upload error code, such as: access denied, etc. For details, please refer to the status of the specific OSS vendor

Note:

When recording fails, in the recording result callback event, duration is 0, starttime is 0, and fileaddress is empty. At this time, you can check upload_status or the upstream status of anchor.
When you only cares about the recording result callback event, you can filter the callback event according to the msgtype type of 2.
If the time points of calling startrecord and stoprecord are close, the callback event of recordtask_m3u8_info may not be triggered.

Notices

The callback message notification is real-time. The callback server retries immediately after the notification fails, and send the message again, and the notification will be tried up to three times. The callback server considers the notification as a failure in any of the following situations:

After sending the message, no response is received in 5 seconds.

The HTTP status code received is not 200.

The sequence of the callback notifications received and the sequence of events occured may not be exactly the same.
To ensure the reliability of the callback notification, callback server may send for more than one time when a recording event occurs, and your server needs to be able to handle duplicate notifications.