Documentation
Agora Basics
Console 官网 Community Technical support
English
search-icon

Media Push Message Notification Service

Last updated 2022/08/23 04:20:35

Agora message notification service can notify your server of events that occur when pushing media streams to the CDN through HTTP or HTTPS requests.

HTTP protocols only support version 1.1 or higher. HTTPS TLS protocols only support version 1.2 or higher.

Enable the service

Contact Agora Technical Support to configure and enable the message notification service. Refer to Message Notification Service for details of Data Format for Message Notification Callback.

Events for the Media Push

The message notification server can notify your server of four types of events that occur when pushing media streams to the CDN:

Converter created

The message notification server notifies your server of this event when you create a Converter by calling the Create method.

The eventType is1 (Converter Created). The following is an example the payload:

{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "name": "show68_vertical",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "codecProfile": "HE-AAC",
                "sampleRate": 48000,
                "bitrate": 128,
                "audioChannels": 1,
                "rtcStreamUids": [
                    201,
                    202
                ]
            },
            "videoOptions": {
                "canvas": {
                    "width": 360,
                    "height": 640,
                    "color": 0
                },
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        },
                        "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
                    },
                    {
                        "rtcStreamUid": 202,
                        "region": {
                            "xPos": 0,
                            "yPos": 320,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        }
                    },
                    {
                        "imageUrl": "http://example.agora.io/watchmark.jpg",
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 2,
                            "width": 36,
                            "height": 64
                        }
                    }
                ],
                "codecProfile": "High",
                "frameRate": 15,
                "bitrate": 400,
                "seiOptions": ""
            }
        },
        "rtmpUrl": "rtmp://example.agora.io/live/show68",
        "idleTimeout": 300,
        "createTs": 1591786766,
        "updateTs": 1591786835,
        "state": "connecting"
    },
    "lts": 1603456600,
    "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • name: String type field. The name of the Converter.
    • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
      • rtcChannel: String type field. The Agora channel name.
      • audioOptions: JSON Object type field. The audio transcoding configuration of the Converter.
        • codecProfile: String type field. The audio codec output by the Converter.
        • sampleRate: Number type field. The audio encoding sampling rate (Hz) output by the Converter.
        • bitrate: Number type field. The audio encoding rate (Kbps) output by the Converter.
        • audioChannels: Number type field. The number of audio channels output by the Converter.
        • rtcStreamUids: JSON Array type field. The user ID or Account of the user participating in the mixing.
      • videoOptions: JSON Object type field. The video transcoding configuration of the Converter.
        • canvas: JSON Object type field. The video canvas.
          • width: Number type field. The width of the canvas (px).
          • height: Number type field. The height of the canvas (px).
          • color: Number type field. The background color of the canvas. This is an RGB color value, expressed as a decimal number. For example, 255 represents blue.
        • layout: JSON Array type field. The content description of the video screen on the canvas. Two elements are supported:
          • RtcStreamView element. The video screen of each user on the canvas. It contains the following fields:
            • rtcStreamUid: Number type field. The user ID of the user to which the video stream belongs.
            • region: JSON Object type field. The display area of the user's video screen on the canvas.
              • xPos: Number type field. The x coordinate (px) of the screen on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
              • yPos: Number type field. The y coordinate (px) of the screen on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin and the y coordinate as the upper left corner of the screen.
              • zIndex: Number type field. The layer number of the screen. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
              • width: Number type field. The width of the screen (px).
              • height: Number type field. The height of the screen (px).
            • placeholderImageUrl: String type field. The HTTP(S) URL of the substitute image.
          • ImageView element. The video picture on the canvas, which can be used as a watermark. It contains the following fields:
            • imageUrl: String type field. The HTTP(S) URL of the image.
            • region: JSON Object type field. The display area of the picture on the canvas.
              • xPos: Number type field. The x coordinate (px) of the image on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
              • yPos: Number type field. The y coordinate (px) of the picture on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin, and the y coordinate as the upper left corner of the screen.
              • zIndex: Number type field. The layer number of the image. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
              • width: Number type field. The width of the image (px).
              • height: Number type field. The height of the image (px).
        • codecProfile: String type field. The encoding specification of the video.
        • frameRate: Number type field. The encoding frame rate (fps) of the video.
        • bitrate: Number type field. The audio encoding rate (Kbps) output by the Converter.
        • seiExtraInfo: String type field. The user SEI information in the video. This is used to send user-defined SEI information to the CDN.
      • rtmpUrl: (Required) String type field. The CDN streaming address.
      • idleTimeOut: Number type field. The maximum time (s) that the Converter is idle. Idle means that all users of the corresponding media streams processed by the Converter have left the channel. After the idle state exceeds the set idleTimeOut, the Converter is destroyed automatically.
      • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
      • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
      • state: String type field. The status of the Converter. If if the state is reported "connecting", the Converter is connecting to the Agora server.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.

Converter's configuration changed

The message notification server notifies your server of this event when you update the configurations of a Converter by calling the Update method.

The eventType is 2 (ConverterUpdatedEvent).

  • Update the converter.transcodeOptions.videoOptions.layout configuration. tThe following is an example payload:
{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "createTs": 1591786766,
        "updateTs": 1591786835,
        "state": "running",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "videoOptions": {
                "layout": [
                    {
                        "rtcStreamUid": 201,
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        },
                        "placeholderImageUrl": "http://example.agora.io/host_placeholder.jpg"
                    },
                    {
                        "rtcStreamUid": 202,
                        "region": {
                            "xPos": 0,
                            "yPos": 320,
                            "zIndex": 1,
                            "width": 360,
                            "height": 320
                        }
                    },
                    {
                        "imageUrl": "http://example.agora.io/watchmark.jpg",
                        "region": {
                            "xPos": 0,
                            "yPos": 0,
                            "zIndex": 2,
                            "width": 36,
                            "height": 64
                        }
                    }
                ],
                "codecProfile": "High",
                "frameRate": 15,
                "bitrate": 400,
                "seiOptions": ""
            }
        }
    },
    "lts": 1603456600,
    "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
    "fields": "id,createTs,updateTs,state,transcodeOptions.videoOptions.layout"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
    • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
    • state: String type field. The running status of the Converter. If the state is"running", the Converter is running properly, and streams are being pushed to the CDN.
    • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
      • rtcChannel: String type field. The Agora channel name.
      • videoOptions: (Optional) JSON Object type field. The video transcoding configuration of the Converter.
        • layout: JSON Array type field. The content description of the video screen on the canvas. Two elements are supported:
          • RtcStreamView element. The video screen of each user on the canvas. It contains the following fields:
            • rtcStreamUid: Number type field. The user ID of the user to which the video stream belongs.
            • region: JSON Object type field. The display area of the user's video screen on the canvas.
              • xPos: Number type field. The x coordinate (px) of the screen on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
              • yPos: Number type field. The y coordinate (px) of the screen on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin and the y coordinate as the upper left corner of the screen.
              • zIndex: Number type field. The layer number of the screen. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
              • width: Number type field. The width of the screen (px).
              • height: Number type field. The height of the screen (px).
            • placeholderImageUrl: String type field. The HTTP(S) URL of the substitute image.
          • ImageView element. The video picture on the canvas, which can be used as a watermark. It contains the following fields:
            • imageUrl: String type field. The HTTP(S) URL of the image.
            • region: JSON Object type field. The display area of the picture on the canvas.
              • xPos: Number type field. The x coordinate (px) of the image on the canvas. This is the lateral displacement relative to the origin, taking the upper left corner of the canvas as the origin and the x coordinate as the upper left corner of the screen.
              • yPos: Number type field. The y coordinate (px) of the picture on the canvas. This is the longitudinal displacement relative to the origin, taking the upper left corner of the canvas as the origin, and the y coordinate as the upper left corner of the screen.
              • zIndex: Number type field. The layer number of the image. The value range is [0,100]. 0 represents the lowest layer. 100 represents the top layer.
              • width: Number type field. The width of the image (px).
              • height: Number type field. The height of the image (px).
      • codecProfile: String type field. The encoding specification of the video.
      • frameRate: Number type field. The encoding frame rate (fps) of the video.
      • bitrate: Number type field. The encoding bitrate (Kbps) of the video.
      • seiExtraInfo: String type field. The user SEI information in the video. This is used to send user-defined SEI information to the CDN.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
  • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.
  • Update the configuration of the list of user IDs or Accounts participating in the mixing in the converter.transcodeOptions.audioOptions. The following is an example payload:
{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "createTs": 1591786766,
        "updateTs": 1591786835,
        "state": "running",
        "transcodeOptions": {
            "rtcChannel": "show68",
            "audioOptions": {
                "rtcStreamUids": [
                    201,
                    202
                ]
            }
        }
    },
    "lts": 1603456600,
    "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
    "fields": "id,createTs,updateTs,state,transcodeOptions.audioOptions.rtcStreamUids"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
    • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
    • state: String type field. The running status of the Converter. If the state is"running", the Converter is running properly, and streams are being pushed to the CDN.
    • transcodeOptions: JSON Object type field. The Converter's transcoding configuration.
      • rtcChannel: String type field. The Agora channel name.
      • audioOptions: JSON Object type field. The audio transcoding configuration of the Converter.
        • rtcStreamUids: JSON Array type field. The user ID or Account of the user participating in the mixing.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
  • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and statefields in the converter field returned by the Agora server.
  • Update other configurations of the converter, such as converter.rtmpUrl:
{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "createTs": 1591786766,
        "updateTs": 1591786835,
        "state": "running",
        "rtmpUrl": "rtmp://example.agora.io/live/show68"
    },
    "lts": 1603456600,
    "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564",
    "fields": "id,createTs,updateTs,state,rtmpUrl"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
    • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
    • state: String type field. The running status of the Converter. If the state is"running", the Converter is running properly, and streams are being pushed to the CDN.
    • rtmpUrl: (Required) String type field. The CDN streaming address.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • xRequestId: String type field, which identifies the UUID (Universal Unique Identifier) of this request. This is the same as the X-Request-ID field in the request header.
  • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

Converter's status changed

The message notification server notifies your server of this event when you have created a Converter and the running state of the Converter changes.

The eventType is 3(ConverterStateChangedEvent). The following is an example payload:

{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "createTs": 1603456600,
        "updateTs": 1603456600,
        "state": "running"
    },
    "lts": 1603456600,
    "fields": "id,createTs,updateTs,state"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
    • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
    • state: String type field. The running status of the Converter.
      • connecting: The Converter is connecting to the Agora server.
      • running: The Converter is running properly, and streams are being pushed to the CDN.
      • failed: There is a failure in pushing streams to the CDN.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.

Converter destroyed

The message notification server will notify your server of this event when a Converter is destroyed, and the streams are stopped being pushed to the CDN.

For the destruction reason, see thedestroyReason field.

The eventType is 4(ConverterDestroyedEvent). The following is an example payload:

{
    "converter": {
        "id": "4c014467d647bb87b60b719f6fa57686",
        "name": "show68_vertical",
        "createTs": 1603456600,
        "updateTs": 1603456600
    },
    "lts": 1603456600,
    "destroyReason": "Delete Request",
    "fields": "id,name,createTs,updateTs"
}
  • The Converter contains the following fields:
    • id: String type field. The ID of the Converter. This is a UUID (Universal Unique Identifier) generated by the Agora server to identify a created Converter.
    • name: String type field. The name of the Converter.
    • createTs: Number type field. The Unix timestamp (s) when the Converter was created.
    • updateTs: Number type field. The Unix timestamp (s) when the Converter configurationwas last updated.
  • lts: Number type field. The Unix timestamp (ms) when the event occurred on the Agora server.
  • destroyReason: String type field, which shows the reason for the destruction of the Converter.
    • Delete Request: The Agora server receives your Delete request.
    • Idle Timeout: After the idle state exceeds the set idleTimeOut, all users of the corresponding media streams processed by the Converter leave the channel.
    • Internal Error: Errors related to the Agora server. For example, hardware failure.
  • fields: String type field. For the field mask of JSON encoding, please refer to the Google protobuf FieldMask document for details. This is used to specify a subset of theconverter field to be returned. In this example, fields specifies a subset of the id, createTs, updateTs, and state fields in the converter field returned by the Agora server.