Media Pull Message Notification Service

Agora's notification server can inform your server of events that occurred in Agora's other servers for various functions through HTTP or HTTPS requests.

Working principle

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.

HTTP/HTTPS request

Agora's notification server sends requests to your server by the POST method. The data structure is in JSON format. The character encoding is UTF-8.

Request header

Content-Type: application/json
Agora-Signature: The signature

To ensure that the communication between Agora's notification server and your server is secure, it is required to verify the signature when using the notification service.

Request body

Events for the Message Notification

Player Created

When you succeed in creating a cloud player by the Create API, Agora's notification server sends a notification for this event to your server.

The eventType is 1(Player Created). The payload contains data with the following structure:

{
  "player": {
    "channelName": "class32",
    "createTs": 1575508644,
    "id": "2a784467d647bb87b60b719f6fa56317",
    "idleTimeout": 300,
    "name": "teacher101",
    "streamUrl": "rtmp://example.agora.io/live/class32/teacher101",
    "token": "2a784467d6",
    "uid": 101,
    "status": "connecting"
  },
  "lts": 1575508644149,
  "xRequestId": "7bbcc8a4acce48c78b53c5a261a8a564"
}

• player: JSON Object. Contains the following fields:
  • channelName: String. The name of the Agora channel.
  • createTs: Number. The Unix timestamp (in seconds) when creating the cloud player.
  • id: String. UUID (Universally Unique Identifier) to identify the cloud player created. It is the ID of the cloud player.
  • idleTimeout: Number. The maximum length of time (in seconds) that the cloud player is idle. The "idle" state means that the media stream is not playing. When the idle state exceeds idleTimeout, the cloud player is automatically destroyed.
  • name: String. The name of the cloud player.
  • streamUrl: String. The RTMP URL of the online media stream.
  • token: String. The authentication token used by the cloud player in the channel.
  • uid: Number. The User ID of the cloud player in the channel.
  • account: String. The User Account of the cloud player in the Agora channel.
  • status: String. The state of the cloud player at runtime:
    • "connecting": Agora's server is connecting to the address of the media stream or detecting the audio and video data.
• lts: Number. The Unix timestamp (ms) when the event occurs in Agora's server for the cloud player function.
• xRequestId: String. UUID (Universally Unique Identifier) to identify this request. It is the same as the X-Request-ID field in the request header.

Player Destroyed

When the cloud player is destroyed, Agora's notification server sends a notification for this event to your server.

For the destruction reason, see the destroyReason field.

The eventType is 3(Player Destroyed). The payload contains data with the following structure:

{
  "player": {
    "channelName": "class32",
    "id": "2a784467d647bb87b60b719f6fa56317",
    "name": "teacher101"
  },
  "lts": 1575508666666,
  "destroyReason": "Delete Request",
  "fields": "player.name,player.channelName,player.id"
}

• player: JSON Object. Contains the following fields:
  • channelName: String. The name of the Agora channel.
  • id: String. UUID (Universally Unique Identifier) to identify the cloud player created. It is the ID of the cloud player.
  • name: String. The name of the cloud player.
• lts: Number. The Unix timestamp (ms) when the event occurs in Agora's server for the cloud player function.
• destroyReason: String. The reason why the cloud player is destroyed:
  • Delete Request: You call the Delete API to successfully destroy the cloud player.
  • Internal Error: The error occurs when setting the parameters and fields related to the Agora channel, such as the token is invalid or expires.
  • Idle Timeout: Within the specified idleTimeout, Agora's server for the cloud player function cannot connect the address of the media stream or the media stream cannot be played.
  • Stream Stopped: Media stream playback ends.
• fields: String. The field mask to represent a set of symbolic field paths. The field mask is encoded as a single string where paths are separated by a comma. It specifies a subset of fields that should be returned. In the sample code, fields specifies to return the name, channelName, and id fields. For details, see Google protobuf FieldMask.

Player Status Changed

When the state of the cloud player at runtime changes, Agora's notification server sends a notification for this event to your server.

The eventType is 4(Player Status Changed). The payload contains data with the following structure:

{
  "player": {
    "channelName": "class32",
    "id": "2a784467d647bb87b60b719f6fa56317",
    "name": "teacher101",
    "status": "running"
  },
  "lts": 1575508645000,
  "fields": "player.name,player.channelName,player.id,player.status"
}

• player: JSON Object. Contains the following fields:
  • channelName: String. The name of the Agora channel.
  • id: String. UUID (Universally Unique Identifier) to identify the cloud player created. It is the ID of the cloud player.
  • name: String. The name of the cloud player.
  • status: String. The state of the cloud player at runtime:
    • "connecting": Agora server for the cloud player function is connecting to the address of the media stream or detecting the audio and video data.
    • "success": Agora server is successfully connected to the address of the media stream.
    • "running": Playing.
    • "failed": Agora's server cannot connect to the address of the media stream, or the media stream cannot be played.
    • stopped: Media stream playback ends.
• lts: Number. The Unix timestamp (ms) when the event occurs in Agora's server for the cloud player function.
• fields：String. The field mask to represent a set of symbolic field paths. The field mask is encoded as a single string where paths are separated by a comma. It specifies a subset of fields that should be returned. In the sample code,fields specifies to return the name, channelName, id and status fields. For details, see Google protobuf FieldMask.