Skip to main content

Channel event type

After enabling the Notifications service, the Agora server will send a channel event notification callback to your server using the HTTPS POST request method. The data format is JSON, the character encoding is UTF-8, and the signature algorithm is HMAC/SHA1 or HMAC/SHA256.

This page introduces the types and descriptions for all events returned in the channel event callback.

Request parameters

Request header

The notification callback header contains the following fields:

FieldDescription
Content-TypeApplication/json
Agora-SignatureThe signature value generated by Agora using the customer key and the HMAC/SHA1 algorithm. You need to use the customer key and the HMAC/SHA1 algorithm to verify the signed value. See Add signature verification for details.
Agora-Signature-V2The signature value generated by Agora using the customer key and the HMAC/SHA256 algorithm. You need to use the customer key and the HMAC/SHA256 algorithm to verify the signed value. See Add signature verification for details.

Request body

The request body of the message notification callback contains the following fields:

FieldTypeDescription
noticeIdStringNotification ID, identifies an event notification from the Agora business server.
productIdNumberBusiness ID, identifies the real-time communication service.
eventTypeNumberThe type of the event. See Channel event types for details.
notifyMsNumberThe Unix timestamp (ms) of the event notification sent by the Agora server to your server. The value is updated when the notification is re-sent.
sidStringSession ID.
payloadJSON ObjectThe specific content of the event. See Channel event types for details.

Request example


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

Channel event types

The Notifications service can notify about the following channel events:

TypeNameDescription
101channel createCreate a channel.
102channel destroyDestroy the channel.
103broadcaster join channelIn the live broadcast scenario, the host joins the channel.
104broadcaster leave channelIn the live broadcast scenario, the host leaves the channel.
105audience join channelIn the live broadcast scenario, the audience joins the channel.
106audience leave channelIn the live broadcast scenario, the audience leaves the channel.
111client role change to broadcasterA member of the audience switches role to become the host.
112client role change to audienceThe host switches roles to become a member of the audience.

channel create

The channel is created, that is, the first user has joined the channel. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the Agora business server.

Payload example:


_4
{
_4
"channelName": "test_webhook",
_4
"ts": 1560396834
_4
}

channel destroy

The last user has left the channel and the channel was destroyed. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the Agora business server.
lastUidNumberThe ID of the last user to leave the channel.
info
If multiple users leave the channel at the same time, the Notifications service may return several lastUids.

Payload example:


_5
{
_5
"channelName": "test_webhook",
_5
"ts": 1560399999,
_5
"lastUid": 12121212
_5
}

broadcaster join channel

The host has joined the channel in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe host’s user ID in the channel.
platformNumberThe platform of the host's device: 1: Android, 2: iOS, 5: Windows, 6: Linux, 7: Web, 8: macOS, 0: Other platforms
clientTypeNumberThis field is only returned if the platform field returns 6. The service type used by the viewer side of the Linux platform, common return values ​​include: 3: Local server recording, 8: Applets, and 10: Cloud recording
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
accountStringThe user ID.

Payload example:


_8
{
_8
"channelName": "test_webhook",
_8
"uid": 12121212,
_8
"platform": 1,
_8
"clientSeq": 1625051030746,
_8
"ts": 1560396843,
_8
"account": "test"
_8
}

broadcaster leave channel

The host has left the channel in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe host’s user ID in the channel.
platformNumberThe platform of the host's device: 1: Android, 2: iOS, 5: Windows, 6: Linux, 7: Web, 8: macOS, 0: Other platforms
clientTypeNumberThis field is only returned if the platform field returns 6. The service type used by the viewer side of the Linux platform, common return values ​​include: 3: Local server recording, 8: Applets, and 10: Cloud recording
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
reasonNumberThe reasons why the host has left the channel:
  • 1: The viewer left the channel normally.
  • 2: The connection between the client and the Agora business server has timed out. Agora SD-RTN™ has not received any data packets from the host for more than 10 seconds, or the connection to a single server has timed out for 4 seconds and has not completed reconnection within 1 second.
  • 3: Permissions issue. For example, the operator can make someone leave the channel through the RESTful API.
  • 4: Internal reason of the Agora business server. The server is adjusting the load, temporarily disconnecting from the client and then reconnecting.
  • 5: The host switches to a new device, forcing the old device to go offline.
  • 9: Since the client has multiple IP addresses, the SDK actively disconnects and reconnects with the Agora business server. This process is invisible to the user. Please check whether the user has multiple public IP addresses or uses a VPN.
  • 10: Due to network connection problems, such as the SDK not receiving any data packets from the Agora business server for more than 4 seconds or a socket connection error, the SDK actively disconnects and reconnects with the Agora business server. This process is invisible to the user. Please check the network connection status.
  • 999: Abnormal user. For example, a user who frequently logs in and out of the channel in a short period of time is considered an abnormal user. Your App server should call the kick API to kick the user out of the channel 60 seconds after receiving the 104 event with reason set to 999. Otherwise, the user may not receive relevant event notifications after joining the channel again.
  • 0: Other reasons.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
durationNumberThe time that the user has been in the channel.
accountstringThe user ID.

Payload example:


_10
{
_10
"channelName": "test_webhook",
_10
"uid": 12121212,
_10
"platform": 1,
_10
"clientSeq": 1625051030789,
_10
"reason": 1,
_10
"ts": 1560396943,
_10
"duration": 600,
_10
"account": "test"
_10
}

audience join channel

The members of the audience have joined the channel in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe audience’s user ID in the channel.
platformNumberThe platform of the audience's device: 1: Android, 2: iOS, 5: Windows, 6: Linux, 7: Web, 8: macOS, 0: Other platforms
clientTypeNumberThis field is only returned if the platform field returns 6. The service type used by the viewer side of the Linux platform, common return values ​​include: 3: Local server recording, 8: Applets, and 10: Cloud recording
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
accountStringThe user ID.

Payload example:


_8
{
_8
"channelName": "test_webhook",
_8
"uid": 12121212,
_8
"platform": 1,
_8
"clientSeq": 1625051035346,
_8
"ts": 1560396843,
_8
"account": "test"
_8
}

audience leave channel

The members of the audience have left the channel in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe audience’s user ID in the channel.
platformNumberThe platform of the audience's device: 1: Android, 2: iOS, 5: Windows, 6: Linux, 7: Web, 8: macOS, 0: Other platforms
clientTypeNumberThis field is only returned if the platform field returns 6. The service type used by the viewer side of the Linux platform, common return values ​​include: 3: Local server recording, 8: Applets, and 10: Cloud recording
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
reasonNumberThe reasons why the host has left the channel:
  • 1: The viewer left the channel normally.
  • 2: The connection between the client and the Agora business server has timed out. Agora SD-RTN™ has not received any data packets from the host for more than 10 seconds, or the connection to a single server has timed out for 4 seconds and has not completed reconnection within 1 second.
  • 3: Permissions issue. For example, the operator can make someone leave the channel through the RESTful API.
  • 4: Internal reason of the Agora business server. The server is adjusting the load, temporarily disconnecting from the client and then reconnecting.
  • 5: The host switches to a new device, forcing the old device to go offline.
  • 9: Since the client has multiple IP addresses, the SDK actively disconnects and reconnects with the Agora business server. This process is invisible to the user. Please check whether the user has multiple public IP addresses or uses a VPN.
  • 10: Due to network connection problems, such as the SDK not receiving any data packets from the Agora business server for more than 4 seconds or a socket connection error, the SDK actively disconnects and reconnects with the Agora business server. This process is invisible to the user. Please check the network connection status.
  • 999: Abnormal user. For example, a user who frequently logs in and out of the channel in a short period of time is considered an abnormal user. Your App server should call the kick API to kick the user out of the channel 60 seconds after receiving the 104 event with reason set to 999. Otherwise, the user may not receive relevant event notifications after joining the channel again.
  • 0: Other reasons.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
durationNumberThe time that the user has been in the channel.
accountstringThe user ID.

Payload example:


_10
{
_10
"channelName": "test_webhook",
_10
"uid": 12121212,
_10
"platform": 1,
_10
"clientSeq": 1625051035390,
_10
"reason": 1,
_10
"ts": 1560396943,
_10
"duration": 600,
_10
"account": "test"
_10
}

client role change to broadcaster

A member of the audience is using the microphone in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe host’s user ID in the channel.
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
accountStringThe user ID.

Payload example:


_7
{
_7
"channelName": "test_webhook",
_7
"uid": 12121212,
_7
"clientSeq": 1625051035469,
_7
"ts": 1560396834,
_7
"account": "test"
_7
}

client role change to audience

The host is off the microphone in the live broadcast scenario. The payload contains the following fields:

FieldData typeDescription
channelNameStringThe name of the channel.
uidNumberThe audience’s user ID in the channel.
clientSeqNumberSerial number identifying the order in which the events occur on the app client. It can be used to sort events for the same user. For details, see Implement online user status tracking.
tsNumberThe Unix timestamp(s) indicating when this event occurred on the business server.
accountStringThe user ID.

Payload example:


_7
{
_7
"channelName": "test_webhook",
_7
"uid": 12121212,
_7
"clientSeq": 16250510358369,
_7
"ts": 1560496834,
_7
"account": "test"
_7
}

vundefined