Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Query user list

GET
https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}

Use this endpoint to get the list of all users in a specified channel. All users in the channel must use the same channel profile; otherwise, the query results may be inaccurate.

The returned list differs based on the channel profile:

  • COMMUNICATION profile: Returns the list of all users in the channel.
  • LIVE_BROADCASTING profile: Returns the list of all hosts and audience members in the channel.

Request​

The request URL and request body is case-sensitive. All requests must use HTTPS.

Request header​

  • Content-Type: application/json
  • The request header must contain the Authorization field. For details, see RESTful authentication.

Path parameters​

appid stringrequired

The App ID of the project. You can get it through one of the following methods:

channelName stringrequired

The channel name.

Query parameters​

QUERY
  • hosts_only stringnullable

    When specified, only the host list is returned. Applicable to the LIVE_BROADCASTING profile only.

Response​

A 200 status code indicates success. The response body contains the following parameters:

OK
  • success boolean

    The state of this request:

    • true: Success.
    • false: Reserved for future use.
  • data object

    User information.

    Show propertiesHide properties
    • channel_exist boolean

      Whether the specified channel exists:

      • true: The channel exists.
      • false: The channel does not exist. When this is false, no other fields are returned.
    • mode number

      The channel profile:

      • 1: The COMMUNICATION profile.
      • 2: The LIVE_BROADCASTING profile.
    • total number

      The total number of users in the channel. Returned only when mode is 1.

    • users array

      User IDs of all users in the channel. Returned only when mode is 1.

    • broadcasters array

      User IDs of all hosts in the channel. Returned only when mode is 2.

    • audience array

      User IDs of the first 10,000 audience members in the channel. Returned only when mode is 2 and hosts_only is not specified.

    • audience_total number

      The total number of audience members in the channel. Returned only when mode is 2 and hosts_only is not specified.

If the status code is not 200, the request fails. See the message field in the response body for the reason for this failure. Refer to Response status codes for details.

Reference​

Synchronizing channel online statistics​

To synchronize online channel statistics, you can use this endpoint or the query user status endpoint. This endpoint requires a lower call frequency and offers higher efficiency, so Agora recommends it for this purpose.

Authorization

This endpoint requires Basic authentication.

Request example

Test this request in Postman or use one of the following code examples:


_4
curl --request GET \
_4
--url https://api.sd-rtn.com/dev/v1/channel/user/<appid>/<channelName> \
_4
--header 'Accept: application/json' \
_4
--header 'Authorization: Basic <your_base64_encoded_credentials>'

Response example

In COMMUNICATION profile:


_11
{
_11
"success": true,
_11
"data": {
_11
"channel_exist": true,
_11
"mode": 1,
_11
"total": 1,
_11
"users": [
_11
906218805
_11
]
_11
}
_11
}

In LIVE_BROADCASTING profile:


_15
{
_15
"success": true,
_15
"data": {
_15
"channel_exist": true,
_15
"mode": 2,
_15
"broadcasters": [
_15
2206227541,
_15
2845863044
_15
],
_15
"audience": [
_15
906219905
_15
],
_15
"audience_total": 1
_15
}
_15
}