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:

Field	Description
`Content-Type`	`Application/json`
`Agora-Signature`	The 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-V2`	The 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:

Field	Type	Description
`noticeId`	String	Notification ID, identifies an event notification from the Agora business server.
`productId`	Number	Business ID, identifies the real-time communication service.
`eventType`	Number	The type of the event. See Channel event types for details.
`notifyMs`	Number	The 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.
`sid`	String	Session ID.
`payload`	JSON Object	The specific content of the event. See Channel event types for details.

Request example

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

Channel event types

The Notifications service can notify about the following channel events:

Type	Name	Description
101	`channel create`	Create a channel.
102	`channel destroy`	Destroy the channel.
103	`broadcaster join channel`	In the live broadcast scenario, the host joins the channel.
104	`broadcaster leave channel`	In the live broadcast scenario, the host leaves the channel.
105	`audience join channel`	In the live broadcast scenario, the audience joins the channel.
106	`audience leave channel`	In the live broadcast scenario, the audience leaves the channel.
111	`client role change to broadcaster`	A member of the audience switches role to become the host.
112	`client role change to audience`	The 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:

Field	Data type	Description
`channelName`	String	The name of the channel.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the Agora business server.

Payload example:

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

`channel destroy`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the Agora business server.

Payload example:

{
    "channelName": "test_webhook",
    "ts": 1560399999
}

`broadcaster join channel`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The host’s user ID in the channel.
`platform`	Number	The platform of the host's device: `1`: Android, `2`: iOS, `5`: Windows, `6`: Linux, `7`: Web, `8`: macOS, `0`: Other platforms
`clientType`	Number	This 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
`clientSeq`	Number	Serial 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`account`	String	The user ID.

Payload example:

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

`broadcaster leave channel`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The host’s user ID in the channel.
`platform`	Number	The platform of the host's device: `1`: Android, `2`: iOS, `5`: Windows, `6`: Linux, `7`: Web, `8`: macOS, `0`: Other platforms
`clientType`	Number	This 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
`clientSeq`	Number	Serial 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.
reason	Number	The 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`duration`	Number	The time that the user has been in the channel.
`account`	string	The user ID.

Payload example:

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

`audience join channel`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The audience’s user ID in the channel.
`platform`	Number	The platform of the audience's device: `1`: Android, `2`: iOS, `5`: Windows, `6`: Linux, `7`: Web, `8`: macOS, `0`: Other platforms
`clientType`	Number	This 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
`clientSeq`	Number	Serial 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`account`	String	The user ID.

Payload example:

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

`audience leave channel`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The audience’s user ID in the channel.
`platform`	Number	The platform of the audience's device: `1`: Android, `2`: iOS, `5`: Windows, `6`: Linux, `7`: Web, `8`: macOS, `0`: Other platforms
`clientType`	Number	This 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
`clientSeq`	Number	Serial 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.
reason	Number	The 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`duration`	Number	The time that the user has been in the channel.
`account`	string	The user ID.

Payload example:

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

`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:

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The host’s user ID in the channel.
`clientSeq`	Number	Serial 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`account`	String	The user ID.

Payload example:

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

`client role change to audience`

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

Field	Data type	Description
`channelName`	String	The name of the channel.
`uid`	Number	The audience’s user ID in the channel.
`clientSeq`	Number	Serial 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.
`ts`	Number	The Unix timestamp(s) indicating when this event occurred on the business server.
`account`	String	The user ID.

Payload example:

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