Overview
Updated
Intro to the Agora channel management APIs.
In addition to the SDK that you integrate into the app client, Agora provides a set of simple, secure, and reliable server-side RESTful APIs to manage real-time audio and video channels.
This page provides detailed documentation for the Agora Channel Management RESTful APIs.
Key features and use cases
| Key feature | Description | Typical use cases |
|---|---|---|
| Manage user privileges | Includes removing specified users from channels and preventing them from sending audio and video streams. | Unauthorized users appear in a live broadcast, users disrupt a room during a live broadcast, the signaling message sent to the client is hijacked, or the user is offline abnormally, which interferes with timely user list updates. |
| Query channel information | Query the list of online channels, users in a channel, and the status of a specified user. | In a use case where the number of concurrent channels is not large, directly query the channel list to sync channel status. In a use case where real-time sync performance is not required, query and sync the user list and status in the channel. |
Authorization
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.
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 RESTful authentication for details.
Domain
All requests are sent to the following domain name: api.agora.io.
The Agora RESTful API supports only HTTPS with TLS 1.0, 1.1, or 1.2. Requests over plain HTTP are not supported.
For example, after implementing basic HTTP authentication, use the following code to send a simple request to obtain the total number of channels and the number of users in each channel:
public class Base64Encoding {
public static void main(String[] args) throws IOException, InterruptedException {
// Customer ID
// Set the AGORA_CUSTOMER_KEY environment variable
final String customerKey = System.getenv("AGORA_CUSTOMER_KEY");
// Customer key
// Set the AGORA_CUSTOMER_SECRET environment variable
final String customerSecret = System.getenv("AGORA_CUSTOMER_SECRET");
// Set the AGORA_APP_ID variable
final String appid = System.getenv("AGORA_APP_ID");
// Concatenate the customer ID and customer secret and encode them using base64
String plainCredentials = customerKey + ":" + customerSecret;
String base64Credentials = new String(Base64.getEncoder().encode(plainCredentials.getBytes()));
// Create the authorization header
String authorizationHeader = "Basic " + base64Credentials;
HttpClient client = HttpClient.newHttpClient();
// Create an HTTP request object
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.agora.io/dev/v1/channel/" + appid))
.GET()
.header("Authorization", authorizationHeader)
.header("Content-Type", "application/json")
.build();
// Send an HTTP request
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
// Add the subsequent processing logic for the response content
}
}package main
import (
"encoding/base64"
"fmt"
"io/ioutil"
"net/http"
"os"
)
func main() {
// Retrieve environment variables
customerKey := os.Getenv("AGORA_CUSTOMER_KEY")
customerSecret := os.Getenv("AGORA_CUSTOMER_SECRET")
appID := os.Getenv("AGORA_APP_ID")
if customerKey == "" || customerSecret == "" || appID == "" {
fmt.Println("Environment variables AGORA_CUSTOMER_KEY, AGORA_CUSTOMER_SECRET, and AGORA_APP_ID must be set.")
return
}
// Concatenate the customer ID and secret, then encode them using Base64
plainCredentials := customerKey + ":" + customerSecret
base64Credentials := base64.StdEncoding.EncodeToString([]byte(plainCredentials))
// Create the authorization header
authorizationHeader := "Basic " + base64Credentials
// Build the request
req, err := http.NewRequest("GET", "https://api.agora.io/dev/v1/channel/"+appID, nil)
if err != nil {
fmt.Println("Error creating request:", err)
return
}
// Add headers
req.Header.Add("Authorization", authorizationHeader)
req.Header.Add("Content-Type", "application/json")
// Create an HTTP client and send the request
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error sending request:", err)
return
}
defer resp.Body.Close()
// Read the response body
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
fmt.Println("Error reading response body:", err)
return
}
// Print the response body
fmt.Println(string(body))
// Add any subsequent processing logic for the response content here
}Use the channel management RESTful API along with the Agora Notifications service for reliable and effective channel management and status synchronization.
Call frequency limit
For each Agora account, not each App ID, the maximum call frequency of every online channel statistics query API is 20 queries per second. The maximum call frequency of every other API is 10 queries per second. If you are frequency limited when calling the APIs, see How can I avoid being frequency limited when calling Agora Server RESTful APIs to optimize API call frequency.
Response status codes
For a description of the response status codes, refer to Response status codes.
