Skip to main content
Android
Linux C

Channel Management REST API

In addition to the Voice/Video SDK integrated into the app client, Agora provides RESTful APIs for channel management, with which you can manage users in the channel and query channel statistics at the app server.

This page provides detailed help for the Agora Channel Management RESTful APIs.

Basic information

This section provides basic information about the Agora Channel Management RESTful APIs.

Domain

All requests are sent to the domain name: api.agora.io. See Ensure service reliability for alternate domain names.

Data format

The Content-Type field in all HTTP request headers is application/json. All requests and responses are in JSON format. All request URLs and request bodies are case-sensitive.

Authentication

The Agora Channel Management RESTful APIs only support HTTPS. Before sending HTTP requests, you must generate a Base64-encoded credential with the Customer ID and Customer Secret provided by Agora, and pass the credential to the Authorization field in the HTTP request header. See HTTP authentication.

Call frequency limit

For each Agora account (not each App ID), the call frequency of each online channel statistics query API is no more than 20 queries per second, and the call frequency of each other API is no more than 10 queries per second. If you are frequency limited when calling the APIs, please see How can I avoid being frequency limited when calling Agora Server RESTful APIs to optimize API call frequency.

Banning user privileges

To maximize the success of core APIs such as POST, PUT, and DELETE, the success rate and accuracy of the GET method may be compromised, especially when the network connection is poor due to abnormal fluctuations. In the response of the GET method, some request parameters may be missing.

Note

When calling POST to create a rule (time is not set to 0), that you need to update or delete later, we recommend the following operations:

  • Save the rule ID returned in the POST request on your server, and rely on this ID for subsequent update and delete operations.
  • To ensure that you can still obtain the rule ID returned in POST during poor network connections, set the timeout for the POST request to 20 seconds or higher. Make sure that the timeout is set to no less than 5 seconds.
  • In case the POST request times out or returns a 504 error, use the response of the GET method to obtain the rule ID. If the rule exists, it indicates that the POST request is successful, and you can save the rule ID on your server.

Creates a rule

Creates a rule of banning specified user privileges.

The user privileges (privileges) that can be banned include the following:

  • join_channel: Joining a channel.

  • publish_audio: Publishing audio.

  • publish_video: Publishing video.

The banning rule works based on the following three fields: cname, uid, and ip.

When you set privileges as join_channel, the rule works as follows:

  • If you set ip, but not cname or uid, then all users with this ip cannot join any channel in the app.

    Using ip as a filter field may incorrectly block users who should not be blocked, for example, in a scenario where multiple users share an IP address.

  • If you set cname, but not uid or ip, then no one can join the channel specified by the cname field.

    Using cname as a filter field directly blocks the channel with the cname.

  • If you set uid, but not cname or ip, then the user with the user ID cannot join any channel in the app.

  • If you set cname and uid, but not ip, then the user with the user ID cannot join the channel specified by the cname field.

When you set privileges as publish_audio or publish_video, the rule works as follows:

  • If you set ip, but not cname or uid, then the users with this ip cannot publish audio or video in any channel of the app.

  • If you set cname, but not uid or ip, then no one can publish audio or video in the channel specified bythe cname field.

  • If you set uid, but not cname or ip, then the user with the user ID cannot publish audio or video inany channel of the app.

  • If you set cname and uid, but not ip, then the user with the user ID cannot publish audio or video inthe channel specified by the cname field.

A user who is kicked out of a channel (that is when you set privileges as join_channel) receives one of the following callbacks based on their platform:

  • Android: The onConnectionStateChanged callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
  • iOS/macOS: The connectionChangedToState callback reports AgoraConnectionChangedBannedByServer(3).
  • Web (3.x): The Client.on("client-banned") callback.
  • Web (4.x): The Client.on("connection-state-change") callback.
  • Windows:The onConnectionStateChanged callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
  • Electron: The AgoraRtcEngine.on("connectionStateChanged") callback reports 3.
  • Unity: The OnConnectionStateChangedHandler callback reports CONNECTION_CHANGED_BANNED_BY_SERVER(3).
  • React Native: The ConnectionStateChanged callback reports BannedByServer(3).
  • Flutter: The ConnectionStateChanged callback reports BannedByServer(3).

Prototype

  • Method: POST
  • Endpoint: https://api.agora.io/dev/v1/kicking-rule

Request parameters

Request body parameters

Pass in the following parameters in the request body:

ParameterData typeRequired/OptionalDescription
appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • cnameStringOptionalThe channel name.
    uidNumberOptionalThe user ID. Do not set it as 0.
    ipStringOptionalThe IP address of the user. Do not set it as 0.
    timeNumberRequiredThe time duration (in minutes) to ban the user. The value range is [1,1440].

    Note

  • If the set value is between 0 and 1, Agora automatically sets the value to 1.
  • If the set value is greater than 1440, Agora automatically sets the value to 1440.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • time_in_secondsNumberRequiredThe time duration (in seconds) to ban the user. The value range is [10,86430].

    Note

  • If the set value is between 0 and 10, Agora automatically sets the value to 10.
  • If the set value is greater than 86430, Agora automatically sets the value to 86430.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • privilegesArrayRequiredThe user privileges you want to block. You can choose the following values:
  • join_channel: String. Bans a user from joining a channel or kicks a user out of a channel.
  • publish_audio: String. Bans a user from publishing audio. You can pass in both publish_audio and publish_video to ban a user from publishing audio and video.
  • publish_video: Bans a user from publishing video. You can pass in both publish_audio and publish_video to ban a user from publishing audio and video.
  • Request example

    Request body


    _10
    {
    _10
    "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
    _10
    "cname": "channel1",
    _10
    "uid": 589517928,
    _10
    "ip": "",
    _10
    "time": 60,
    _10
    "privileges": [
    _10
    "join_channel"
    _10
    ]
    _10
    }

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    idNumberThe rule ID. If you want to update or delete the rule, you need the rule ID to specify the rule.

    Response example

    The following is a response example for a successful request:


    _4
    {
    _4
    "status": "success",
    _4
    "id": 1953
    _4
    }

    Gets the rule list

    Gets the list of all banning rules.

    Prototype

    • Method: GET
    • Endpoint: https://api.agora.io/dev/v1/kicking-rule

    Request parameters

    Query parameters

    Pass the following query parameters in the request URL:

    ParameterTypeRequired or OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    rulesArrayThe list of banning rules. This array consists of multiple objects. Each object contains the information on one banning rule and includes the following fields:
    • id: Number. The rule ID. If you want to update or delete the rule, you need the rule ID to specify the rule.
    • appid: String. The App ID of the project.
    • uid: Number. The user ID.
    • opid: Number. The operation ID, which can be used to track operation records when troubleshooting.
    • cname: String. The channel name.
    • ip: String. The IP address of the user.
    • ts: String. The UTC time when this rule expires.
    • privileges: Array. User privileges, including the following values:
      • join_channel: String. Bans a user from joining a channel or kicks a user out of a channel.
      • publish_audio: String. Bans a user from publishing audio.
      • publish_video: String. Bans a user from publishing video.
    createAtStringThe UTC time when this rule is created.
    updateAtStringThe UTC time when this rule is updated.

    Response example

    The following is a response example for a successful request:


    _19
    {
    _19
    "status": "success",
    _19
    "rules": [
    _19
    {
    _19
    "id": 1953,
    _19
    "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
    _19
    "uid": 589517928,
    _19
    "opid": 1406,
    _19
    "cname": "11",
    _19
    "ip": "192.168.0.1",
    _19
    "ts": "2018-01-09T07:23:06.000Z",
    _19
    "privileges": [
    _19
    "join_channel"
    _19
    ],
    _19
    "createAt": "2018-01-09T06:23:06.000Z",
    _19
    "updateAt": "2018-01-09T14:23:06.000Z"
    _19
    }
    _19
    ]
    _19
    }

    Updates a rule

    Updates the expiration time of a specified banning rule.

    Prototype

    • Method: PUT
    • Endpoint: https://api.agora.io/dev/v1/kicking-rule

    Request parameters

    Request body parameters

    Pass in the following parameters in the request body:

    ParameterTypeRequired/OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • idNumberRequiredThe ID of the rule that you want to update.
    timeNumberRequiredThe time duration (in minutes) to ban the user. The value range is [1,1440].

    Note

  • If the set value is between 0 and 1, Agora automatically sets the value to 1.
  • If the set value is greater than 1440, Agora automatically sets the value to 1440.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • time_in_secondsNumberRequiredThe time duration (in seconds) to ban the user. The value range is [10,86430].

    Note

  • If the set value is between 0 and 10, Agora automatically sets the value to 10.
  • If the set value is greater than 86430, Agora automatically sets the value to 86430.
  • If the set value is 0, the banning rule does not take effect. The server sets all users that conform to the rule offline, and users can log in again to rejoin the channel.
  • Use either time or time_in_seconds. If you set both parameters, the time_in_seconds parameter takes effect; if you set neither of these parameters, the Agora server automatically sets the banning time duration to 60 minutes, that is, 3600 seconds.
  • Request example

    Request body


    _5
    {
    _5
    "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
    _5
    "id": 1953,
    _5
    "time": 60
    _5
    }

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    resultObjectThe result of the update:
  • id: String. The rule ID.
  • ts: String. The UTC time when the rule expires.
  • Response example

    The following is a response example for a successful request:


    _7
    {
    _7
    "status": "success",
    _7
    "result": {
    _7
    "id": 1953,
    _7
    "ts": "2018-01-09T08:45:54.545Z"
    _7
    }
    _7
    }

    Deletes a rule

    Deletes a specified banning rule.

    Prototype

    • Method: DELETE
    • Endpoint: https://api.agora.io/dev/v1/kicking-rule

    Request body parameters

    The following parameters are required in the request body:

    ParameterTypeRequired/OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • idNumberRequiredThe ID of the rule that you want to delete.

    Request example

    Request body


    _4
    {
    _4
    "appid": "4855xxxxxxxxxxxxxxxxxxxxxxxxeae2",
    _4
    "id": 1953
    _4
    }

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    statusStringThe status of this request. success means the request succeeds.
    idStringThe ID of the rule that you want to delete.

    Response example

    The following is a response example for a successful request:


    _4
    {
    _4
    "status": "success",
    _4
    "id": 1953
    _4
    }

    Online channel statistics query

    Gets the user status

    Gets the status of a specified user.

    This method checks if a specified user is in a specified channel, and if yes, the role of this user in the channel.

    Prototype

    • Method: GET
    • Endpoint: https://api.agora.io/dev/v1/channel/user/property/{appid}/{uid}/{channelName}

    Request parameters

    Path parameters

    Pass the following path parameters in the request URL:

    ParameterTypeRequired/OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • uidNumberRequiredThe user ID.

    Note: This parameter does not support string user accounts. Ensure that you use the integer user ID.

    channelNameStringRequiredThe channel name.

    Request example

    Request URL


    _1
    https://api.agora.io/dev/v1/channel/user/property/12sfegxxxxxxxxxxxx365/2845863044/test

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    successBooleanThe state of this request:
    • true: Success.
    • false: Reserved for future use.
    dataObjectUser statistics, including the following fields:
  • in_channel: Boolean. Whether the user is in the channel. When the value of in_channel is false, all other fields are not returned .
  • join: Number. The Unix timestamp in seconds of when the user joins the channel.
  • role: Number. The role of the user in the channel:
    • 0: Unknown user role.
    • 1: User, in a communication channel.
    • 2: Host, in the channel.
    • 3: Audience, in the channel.
  • platform: Number. The platform of the user's device. Common return values include:
    • 1: Android
    • 2:iOS
    • 5: Windows
    • 6: Linux
    • 7: Web
    • 8: macOS
    • 0: Others
  • |

    Response example

    The following is a response example for a successful request:


    _10
    {
    _10
    "success": true,
    _10
    "data": {
    _10
    "join": 1640330382,
    _10
    "uid": 2845863044,
    _10
    "in_channel": true,
    _10
    "platform": 7,
    _10
    "role": 2
    _10
    }
    _10
    }

    Gets the user list

    Gets the list of all users in a specified channel.

    The return list differs with the channel profile as follows:

    • In COMMUNICATION profile, this API returns the list of all users in the channel.
    • In LIVE_BROADCASTING profile, this API returns the list of all hosts and audience members in the channel.

    • Users in a channel must use the same channel profile; otherwise, the query results may be inaccurate.
    • You can synchronize the online channel statistics either by calling this API or by calling the Gets the user status API. Compared with the Gets the user status API, this API requires a lower call frequency and has a higher query efficiency. Therefore, Agora recommends using this API to query online channel statistics.
    .

    Prototype

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

    Request parameters

    Path parameters

    Pass the following path parameters in the request URL:

    ParameterTypeRequired/OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • channelNameStringRequiredThe channel name.

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    successBooleanThe state of this request:
  • true: Success.
  • false: Reserved for future use.
  • dataObjectUser information, including the following fields:
    • channel_exist: Boolean. Whether the specified channel exists:
      • true: The channel exists.
      • false: The channel does not exist.
      Note: All other fields are not returned when the value of channel_exist is false.
    • mode: Number. The channel profile:
      • 1:The COMMUNICATION profile.
      • 2: The LIVE_BROADCASTING profile.
    • total: Number. The total number of the users in the channel. This field is returned only when mode is 1.
    • users: Array. User IDs of all users in the channel. This field is returned only when mode is 1.
    • broadcasters:Array. User IDs of all hosts in the channel. This field is returned only when mode is 2.
    • audience: Array. User IDs of the first 10,000 audience members in the channel. This field is returned only when mode is 2.
    • audience_total: Number. The total number of audience members in the channel. This field is returned only when mode is 2.

    Response example

    The following is a response example for a successful request:

    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
    }

    Gets the channel list

    Gets the list of all channels under a specified project.

    This API gets the channel list by page. In the request URL, you can specify the page number and the number of channels shown on the page. A successful request returns the channel list of the specified page according to the set page_size.

    If the number of users in a channel changes frequently, the query results may be inaccurate. The following situations may occur:
    • A channel appears repeatedly in different pages.
    • A channel does not appear in any page.

    Prototype

    • Method: GET
    • Endpoint: https://api.agora.io/dev/v1/channel/{appid}

    Request parameters

    Path parameters

    Pass the following path parameters in the request URL:

    ParameterTypeRequired/OptionalDescription
    appidStringRequiredThe App ID of the project. You can get it through one of the following methods:
  • Copy from the Agora Console.
  • Call the Get all projects API, and read the value of the vendor_key field in the response body.
  • Query parameters

    Pass the following query parameters in the request URL:

    ParameterTypeRequired/OptionalDescription
    page_noNumberOptionalThe page number that you want to query. The default value is 0, that is, the first page.

    Note: The value of page_no cannot exceed (the total number of channels/the value of page_size - 1); otherwise, the specified page does not contain any channel.

    page_sizeNumberOptionalThe number of channels on a page. The value range is [1,500], and the default value is 100.

    Response parameters

    For details about possible response status codes, see the Response status codes table.

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

    If the status code is 200, the request succeeds, and the response body includes the following parameters:

    ParameterTypeDescription
    successBooleanThe state of this request:
  • true: Success.
  • false: Reserved for future use.
  • dataObjectChannel statistics, including the following fields:
    • channels: Array. The list of channels. This array contains multiple objects. Each object shows the information on a channel and includes the following fields:
      • channel_name: String. The channel name.
      • user_count: Number. The total number of users in the channel.
      Note: If the specified page does not contain any channel, this field is empty.
    • total_size: Number. The total number of channels under the specified project.

    Response example

    The following is a response example for a successful request:


    _12
    {
    _12
    "success": true,
    _12
    "data": {
    _12
    "channels": [
    _12
    {
    _12
    "channel_name": "lkj144",
    _12
    "user_count": 3
    _12
    }
    _12
    ],
    _12
    "total_size": 1
    _12
    }
    _12
    }

    Response status codes

    Response status codeDescription
    200The operation is successful.
    400Bad request.
    401Unauthorized (incorrect App ID/Customer Certificate).
    403Forbidden.
    404The requested resource could not be found.
    415Unsupported media type. Make sure that you set Content-Typein Headers as application/json.
    429Too many requests.
    500Internal error of the Agora RESTful API service.

    Ensure service reliability

    This section presents the overall strategy you use to ensure high availability of REST services.

    Switch the domain name

    To ensure high availability of REST services, Agora enables you to switch domain names when you experience service outage due to regional network failures. Take the following steps to set up and switch your domain name:

    1. Set the primary domain name based on the location of your service server:

      • If the DNS address of the service server is located in a country or region other than mainland China, set the primary domain name to api.agora.io.
      • If the DNS address of the service server is in mainland China, set the primary domain name to api.sd-rtn.com.
    2. If your attempt to initiate a RESTful API request using the primary domain fails, set up your retry strategy as follows:

      1. Primary domain retry: Retry using the same primary domain name.

      2. Alternate domain retry:

        • If the current primary domain name is api.sd-rtn.com, use api.agora.io as the alternate domain name.
        • If the current primary domain name is api.agora.io, use api.sd-rtn.com as the alternate domain name.
      3. Adjacent domain retry: If alternate domain retry fails, retry using the domain name adjacent to the current region.

        For example, suppose your business server is located in Europe. You set the primary domain name to api.agora.io, and the business server resolves the primary domain name to Germany. Germany is located in central Europe (api-eu-central-1.agora.io). The domain name table shows that the adjacent area is West Europe. Use the api-eu-west-1.agora.io or api-eu-west-1.sd-rtn.com domain name to retry.

    Precautions

    Take the following precautions when setting up your retry strategy:

    • To avoid exceeding the QPS limit with retry requests, best practice is to use a back-off strategy. For example, wait 1 second before you retry for the first time, wait 3 seconds before retrying the second time, and wait 6 seconds before retry a third time.

    • If the request fails because of a network problem rather than a DNS domain name resolution problem, skip alternate domain retry and proceed to adjacent domain retry.

    • Before switching to the region domain name, ensure that the REST services you wish to use, for example, cloud recording or channel management, are deployed in that region.

    Domain name table

    The following table shows the primary and region domain names for various regions.

    Primary domain nameRegion domain nameRegion
    api.sd-rtn.comapi-us-west-1.sd-rtn.comWestern United States
    api-us-east-1.sd-rtn.comEastern United States
    api-ap-southeast-1.sd-rtn.comSoutheast Asia Pacific
    api-ap-northeast-1.sd-rtn.comNortheast Asia Pacific
    api-eu-west-1.sd-rtn.comWestern Europe
    api-eu-central-1.sd-rtn.comCentral Europe
    api-cn-east-1.sd-rtn.comEast China
    api-cn-north-1.sd-rtn.comNorth China
    api.agora.ioapi-us-west-1.agora.ioWestern United States
    api-us-east-1.agora.ioEastern United States
    api-ap-southeast-1.agora.ioSoutheast Asia Pacific
    api-ap-northeast-1.agora.ioNortheast Asia Pacific
    api-eu-west-1.agora.ioWestern Europe
    api-eu-central-1.agora.ioCentral Europe
    api-cn-east-1.agora.ioEast China
    api-cn-north-1.agora.ioNorth China
    vundefined