Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

    Receive notifications about recording events

    A webhook is a user-defined callback over HTTP. You use webhooks to notify your app or back-end system when certain Cloud Recording events occur. Agora Notifications enables you to subscribe to events and receive notifications about them across multiple product lines.

    Understand the tech​

    Using Agora Console you subscribe to specific events for your project and configure the URL of the webhooks to receive these events. Agora sends notifications of your events to your webhook every time they occur. Your server authenticates the notification and returns 200 Ok to confirm reception. You use the information in the JSON payload of each notification to give the best user experience to your users.

    The following figure illustrates the workflow when Notifications is enabled for the specific Cloud Recording events you subscribe to:

    cloud-recording

    1. A user commits an action that creates an event.
    2. Notifications sends an HTTPS POST request to your webhook.
    3. Your server validates the request signature, then sends a response to Notifications within 10 seconds. The response body must be in JSON.

    If Notifications receives 200 OK within 10 seconds of sending the initial notification, the callback is considered successful. If these conditions are not met, Notifications immediately resends the notification. The interval between notification attempts gradually increases. Notifications stops sending notifications after three retries.

    Prerequisites​

    To set up and use Notifications, you must have:

    Handle notifications for specific events​

    In order to handle notifications for the events you subscribe to, you need to:

    Create your webhook​

    Once Notifications is enabled, Agora SD-RTN™ sends notification callbacks as HTTPS POST requests to your webhook when events that you are subscribed to occur. The data format of the requests is JSON, the character encoding is UTF-8, and the signature algorithm is HMAC/SHA1 or HMAC/SHA256.

    For Notifications, a webhook is an endpoint on an HTTP server that handles these requests. In a production environment you write this in your web infrastructure, for development purposes best practice is to create a simple local server and use a service such as ngrok to supply a public URL that you register with Agora SD-RTN™ when you enable Notifications.

    To do this, take the following steps:

    1. Set up Go

      Ensure you have Go installed on your system. If not, download and install it from the official Go website.

    2. Create a Go project for your server

      Create a new directory for your project and navigate into it:


      _2
      mkdir agora-webhook-server
      _2
      cd agora-webhook-server

      In the project directory, create a new file main.go. Open the file in your preferred text editor and add the following code:


      _62
      package main
      _62
      _62
      import (
      _62
      "encoding/json"
      _62
      "fmt"
      _62
      "io"
      _62
      "log"
      _62
      "net/http"
      _62
      )
      _62
      _62
      type WebhookRequest struct {
      _62
      NoticeID string `json:"noticeId"`
      _62
      ProductID int64 `json:"productId"`
      _62
      EventType int `json:"eventType"`
      _62
      Payload Payload `json:"payload"`
      _62
      }
      _62
      _62
      type Payload struct {
      _62
      ClientSeq int64 `json:"clientSeq"`
      _62
      UID int `json:"uid"`
      _62
      ChannelName string `json:"channelName"`
      _62
      }
      _62
      _62
      func rootHandler(w http.ResponseWriter, r *http.Request) {
      _62
      response := `<h1>Agora Notifications demo</h1>`
      _62
      w.WriteHeader(http.StatusOK)
      _62
      w.Write([]byte(response))
      _62
      }
      _62
      _62
      func ncsHandler(w http.ResponseWriter, r *http.Request) {
      _62
      agoraSignature := r.Header.Get("Agora-Signature")
      _62
      fmt.Println("Agora-Signature:", agoraSignature)
      _62
      _62
      body, err := io.ReadAll(r.Body)
      _62
      if err != nil {
      _62
      http.Error(w, "Unable to read request body", http.StatusBadRequest)
      _62
      return
      _62
      }
      _62
      _62
      var req WebhookRequest
      _62
      if err := json.Unmarshal(body, &req); err != nil {
      _62
      http.Error(w, "Invalid JSON", http.StatusBadRequest)
      _62
      return
      _62
      }
      _62
      _62
      fmt.Printf("Event code: %d Uid: %d Channel: %s ClientSeq: %d\n",
      _62
      req.EventType, req.Payload.UID, req.Payload.ChannelName, req.Payload.ClientSeq)
      _62
      _62
      w.WriteHeader(http.StatusOK)
      _62
      w.Write([]byte("Ok"))
      _62
      }
      _62
      _62
      func main() {
      _62
      http.HandleFunc("/", rootHandler)
      _62
      http.HandleFunc("/ncsNotify", ncsHandler)
      _62
      _62
      port := ":8080"
      _62
      fmt.Printf("Notifications webhook server started on port %s\n", port)
      _62
      if err := http.ListenAndServe(port, nil); err != nil {
      _62
      log.Fatalf("Failed to start server: %v", err)
      _62
      }
      _62
      }

    3. Run your Go server

      Run the server using the following command:


      _1
      go run main.go

    4. Create a public URL for your server

      In this example you use ngrok to create a public URL for your server.

      1. Download and install ngrok. If you have Chocolatey, use the following command:


        _1
        choco install ngrok

      2. Add an authtoken to ngrok:


        _1
        ngrok config add-authtoken <authToken>

        To obtain an authToken, sign up with ngrok.

      3. Start a tunnel to your local server using the following command:


        _1
        ngrok http 127.0.0.1:8080

        You see a Forwarding URL and a Web Interface URL in the console. Open the web interface URL in your browser.

    5. Test the server

      Open a web browser and navigate to the public URL provided by ngrok to see the root handler response.

      Use curl, Postman, or another tool to send a POST request to https://<ngrok_url>/ncsNotify with the required JSON payload.

      Example using curl:


      _13
      curl -X POST <ngrok_url>/ncsNotify \
      _13
      -H "Content-Type: application/json" \
      _13
      -H "Agora-Signature: your_signature" \
      _13
      -d '{
      _13
      "noticeId": "some_notice_id",
      _13
      "productId": 12345,
      _13
      "eventType": 1,
      _13
      "payload": {
      _13
      "clientSeq": 67890,
      _13
      "uid": 123,
      _13
      "channelName": "test_channel"
      _13
      }
      _13
      }'

      Make sure you replace ngrok_url with the forwarding url.

      Once the HTTP request is successful, you see the following JSON payload in your browser:


      _10
      {
      _10
      "noticeId": "some_notice_id",
      _10
      "productId": 12345,
      _10
      "eventType": 1,
      _10
      "payload": {
      _10
      "clientSeq": 67890,
      _10
      "uid": 123,
      _10
      "channelName": "test_channel"
      _10
      }
      _10
      }

    Enable Notifications​

    To enable Notifications:

    1. Log in to Agora Console. On the Projects tab, locate the project for which you want to enable Notifications and click Configure.

    2. In the Features section, locate Notifications, and click Enable.

    3. On the configuration page, click on the service for which you want to enable notifications. The item expands to show configuration options.

    4. Fill in the following information:

      • Event: Select all the events that you want to subscribe to.

        If the selected events generate a high number of queries per second (QPS), ensure that your server has sufficient processing capacity.

      • Receiving Server Region: Select the region where your server that receives the notifications is located. Agora connects to the nearest Agora node server based on your selection.

      • Receiving Server URL Endpoint: The HTTPS public address of your server that receives the notifications. For example, https://1111-123-456-789-99.ap.ngrok.io/ncsNotify.

        info

        For enhanced security, Notifications no longer supports HTTP addresses.

        • To reduce the delay in notification delivery, best practice is to activate HTTP persistent connection (also called HTTP keep-alive) on your server with the following settings:

          • MaxKeepAliveRequests: 100 or more
          • KeepAliveTimeout: 10 seconds or more

      • Whitelist: If your server is behind a firewall, check the box here, and ensure that you call the IP address query API to get the IP addresses of the Agora Notifications server and add them to the firewall's allowed IP list.

    5. Copy the Secret displayed against the product name by clicking the copy icon. You use this secret to Add signature verification.

    6. Press Save. Agora performs a health test for your configuration as follows:

      1. The Notifications health test generates test events that correspond to your subscribed events, and then sends test event callbacks to your server.

      2. After receiving each test event callback, your server must respond within 10 seconds with a status code of 200. The response body must be in JSON format.

      3. When the Notifications health test succeeds, read the prompt and press Save Notifications Configuration. After your configuration is saved, the Status of Notifications shows Enabled.

        If the Notifications health test fails, follow the prompt on the Agora Console to troubleshoot the error. Common errors include the following:

        • Request timeout (590): Your server does not return the status code 200 within 10 seconds. Check whether your server responds to the request properly. If your server responds to the request properly, contact Agora Technical Support to check if the network connection between the Agora Notifications server and your server is working.

        • Domain name unreachable (591): The domain name is invalid and cannot be resolved to the target IP address. Check whether your server is properly deployed.

        • Certificate error (592): The Agora Notifications server fails to verify the SSL certificates returned by your server. Check if the SSL certificates of your server are valid. If your server is behind a firewall, check whether you have added all IP addresses of the Agora Notifications server to the firewall's allowed IP list.

        • Other response errors: Your server returns a response with a status code other than 200. See the prompt on the Agora Console for the specific status code and error messages.

    Add signature verification​

    To communicate securely between Notifications and your webhook, Agora SD-RTN™ uses signatures for identity verification as follows:

    1. When you configure Notifications in Agora Console, Agora SD-RTN™ generates a secret you use for verification.

    2. When sending a notification, Notifications generates two signature values from the secret using HMAC/SHA1 and HMAC/SHA256 algorithms. These signatures are added as Agora-Signature and Agora-Signature-V2 to the HTTPS request header.

    3. When your server receives a callback, you can verify Agora-Signature or Agora-Signature-V2:

      • To verify Agora-Signature, use the secret, the raw request body, and the crypto/sha1 algorithm.
      • To verify Agora-Signature-V2, use the secret, the raw request body, and the crypto/sha256 algorithm.

    The following sample code uses crypto/sha1.

    To add signature verification to your server, take the following steps:

    1. In the main.go file, replace your imports with with the following:


      _10
      import (
      _10
      "crypto/hmac"
      _10
      "crypto/sha1"
      _10
      "encoding/hex"
      _10
      "encoding/json"
      _10
      "fmt"
      _10
      "io"
      _10
      "log"
      _10
      "net/http"
      _10
      )

    2. Add the following code after the list of imports:


      _17
      // Replace with your NCS secret
      _17
      const secret = "<Replace with your secret code>"
      _17
      _17
      // calcSignatureV1 computes the HMAC/SHA256 signature for a given payload and secret
      _17
      func calcSignatureV1(secret, payload string) string {
      _17
      mac := hmac.New(sha1.New, []byte(secret))
      _17
      mac.Write([]byte(payload))
      _17
      return hex.EncodeToString(mac.Sum(nil))
      _17
      }
      _17
      _17
      // verify checks if the provided signature matches the HMAC/SHA256 signature of the request body
      _17
      func verify(requestBody, signature string) bool {
      _17
      calculatedSignature := calcSignatureV1(secret, requestBody)
      _17
      fmt.Println("Calculated Signature:", calculatedSignature)
      _17
      fmt.Println("Received Signature:", signature)
      _17
      return calculatedSignature == signature
      _17
      }

    3. In the main.go file, add the following code after fmt.Println("Request Body:", string(body)):


      _5
      // Verify the signature
      _5
      if !verify(string(body), agoraSignature) {
      _5
      http.Error(w, "Invalid signature", http.StatusUnauthorized)
      _5
      return
      _5
      }

    4. To test the server, follow the steps given in the Enable notifications section.

    5. When you receive an event from the console, and if the signature matches, the event details are displayed in your browser.

    Reference​

    This section contains in depth information about Notifications.

    Request Header​

    The header of notification callbacks contains the following fields:

    Field nameValue
    Content-Typeapplication/json
    Agora-SignatureThe signature generated by Agora using the Secret and the HMAC/SHA1 algorithm. You need to use the Secret and HMAC/SHA1 algorithm to verify the signature value. For details, see Signature verification.
    Agora-Signature-V2The signature generated by Agora using the Secret and the HMAC/SHA256 algorithm. You need to use the Secret and the HMAC/SHA256 algorithm to verify the signature value. For details, see Signature verification.

    Request Body​

    The request body of notification callbacks contains the following fields:

    Field nameTypeDescription
    noticeIdStringThe notification ID, identifying the notification callback when the event occurs.
    productIdNumberThe product ID:
    • 1: Realtime Communication (RTC) service
    • 3: Cloud Recording
    • 4: Media Pull
    • 5: Media Push
    eventTypeNumberThe type of event being notified. For details, see event types.
    notifyMsNumberThe Unix timestamp (ms) when Notifications sends a callback to your server. This value is updated when Notifications resends the notification callback.
    payloadJSON ObjectThe content of the event being notified. The payload varies with event type.

    Example​


    _9
    {
    _9
    "noticeId":"2000001428:4330:107",
    _9
    "productId":1,
    _9
    "eventType":101,
    _9
    "notifyMs":1611566412672,
    _9
    "payload":{
    _9
    ...
    _9
    }
    _9
    }

    Event types​

    You can subscribe to the following Cloud Recording events from Agora Console:

    eventTypeserviceTypeEvent description
    10 (cloud recording service)An error occurs during the recording.
    20 (cloud recording service)A warning occurs during the recording.
    30 (cloud recording service)The status of the Agora Cloud Recording service changes.
    40 (cloud recording service)The M3U8 playlist file is generated.
    110 (cloud recording service)The cloud recording service has ended its tasks and exited.
    120 (cloud recording service)The cloud recording service has enabled the high availability mechanism.
    302 (uploader module)The upload service starts.
    312 (uploader module)All the recorded files are uploaded to the specified third-party cloud storage.
    322 (uploader module)All the recorded files are uploaded, but at least one file is uploaded to Agora Cloud Backup.
    332 (uploader module)The progress of uploading the recorded files to the cloud storage.
    401 (recorder module)The recording starts.
    411 (recorder module)The recording exits.
    421 (recorder module)The recording service syncs the information of the recorded files.
    431 (recorder module)The state of the audio stream changes.
    441 (recorder module)The state of the video stream changes.
    451 (recorder module)The screenshot is captured successfully.
    604 (extension services)The uploader for ApsaraVideo for VoD has started and successfully acquired the upload credential.
    614 (extension services)All recorded files have been uploaded to ApsaraVideo for VoD.
    706 (web page recording module)Web page recording starts.
    716 (web page recording module)Web page recording stops.
    726 (web page recording module)The web page to record uses a feature that is unsupported by web page recording. The recording service will stop immediately.
    736 (web page recording module)The web page reloads.
    908（download module）The recording service fails to download the recorded files.
    1006（web page recording module）The CDN streaming status of the web page recording changes.
    10010 (cloud recording service)The result of the transcoding.

    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 in the following section. Notifications may add new fields to details in the future. To ensure backward compatibility, the service will not change the data format of existing fields.

    The relevant fields of each Agora Cloud Recording callback event 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.

    Examples​

    • Individual recording:


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

    • Composite recording with no MP4 files generated:


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

    • Composite recording with MP4 files generated:


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

    • Web page recording with MP4 files generated:


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

    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.

    Examples​

    • Individual recording:


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

    • Composite recording with no MP4 files generated:


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

    • Composite recording with MP4 files generated:


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

    • Web page recording with MP4 files generated:


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

    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_INIT0: The initialization fails.
      LEAVE_CODE_SIG2 (binary 10): The AgoraCoreService process receives the SIGINT signal.
      LEAVE_CODE_NO_USERS4 (binary 100): The recording server automatically leaves the channel and stops recording because the channel has no user.
      LEAVE_CODE_TIMER_CATCH8 (binary 1000): Ignore it.
      LEAVE_CODE_CLIENT_LEAVE16 (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>". The 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.
    Error CodeMessageDescription
    0okNormal, the user stops the recording.
    1max_recording_hourThe recording time reaches the set maximum recording length (maxRecordingHour), which causes the recording to stop.
    2capability_limitThe web page to be recorded uses an unsupported function, causing the web page recording to stop.
    3start_engine_failedThe recording engine failed to start, causing the web page recording to stop.
    4page_load_timeoutWhen you use the web page load timeout detection, the web page load timeout causes the web page recording to stop.
    5access_url_failedAn error occurred when opening the web page to be recorded, which causes the web page recording to stop.
    6recorder_error The web page recording has an error and cannot continue, causing the web page recording to stop.

    Example​


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

    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 if the web page load detection function is enabled and there is a 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.
    Error codeDescription
    32An error occurs in the configuration of the third-party cloud storage.
    47The recording file upload fails.
    51An error occurs when the uploader processes the recorded files.
    Warning codeDescription
    31The recording service re-uploads the slice file to the specified cloud storage.
    32The recording service re-uploads the slice file to Agora Cloud Backup.

    Error codes for the Agora Cloud Recording service​

    Error codeDescription
    50A timeout occurs in uploading the recorded files.
    52A timeout occurs in starting the Cloud Recording Service.

    Status codes for the Agora Cloud Recording service​

    Status codeDescription
    0The recording has not started.
    1The initialization is complete.
    2The recorder is starting.
    3The uploader is ready.
    4The recorder is ready.
    5The first recorded file is uploaded. After uploading the first file, the status is 5 when the recording is running.
    6The recording stops.
    7The Agora Cloud Recording service stops.
    8The recording is ready to exit.
    20The recording exits abnormally.

    IP address query API​

    If your server that receives notification callbacks is behind a firewall, call the IP address query API to retrieve the IP addresses of Notifications and configure your firewall to trust all these IP addresses.

    Agora occasionally adjusts the Notifications IP addresses. Best practice is to call this endpoint at least every 24 hours and automatically update the firewall configuration.

    Prototype​

    • Method: GET
    • Endpoint: https://api.agora.io/v2/ncs/ip

    Request header​

    Authorization: You must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and then pass the credential to the Authorization field in the HTTP request header.

    Request body​

    This API has no body parameters.

    Response body​

    When the request succeeds, the response body looks like the following:


    _14
    {
    _14
    "data": {
    _14
    "service": {
    _14
    "hosts": [
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    },
    _14
    {
    _14
    "primaryIP": "xxx.xxx.xxx.xxx"
    _14
    }
    _14
    ]
    _14
    }
    _14
    }
    _14
    }

    Each primary IP field shows an IP address of Notifications server. When you receive a response, you need to note the primary IP fields and add all these IP addresses to your firewall's allowed IP list.

    Considerations​

    • Notifications does not guarantee that notification callbacks arrive at your server in the same order as events occur. Implement a strategy to handle messages arriving out of order.

    • For improved reliability of Notifications, your server may receive more than one notification callback for a single event. Your server must be able to handle repeated messages.

      Tip

      To implement a strategy to ensure that you log only one callback event and ignore duplicate events, use a combination of the noticeId and notifyMs fields in the response body.

    vundefined