Overview

The REST APIs provide server-side messaging capabilities that complement the Signaling SDK. Send messages to users and channels, retrieve conversation history, and track user events from your backend without requiring recipients to be actively connected.

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

• Authentication: All APIs require Basic Auth for authentication.
• Request: Refer to the respective API examples.
• Response: The response content is in JSON format.
• Base URL: https://api.agora.io/dev/v2/project/<appid>
  where <appid> is the Agora app ID for your project.

info

• All the request URLs and request bodies are case-sensitive.
• For each app ID, the maximum combined frequency of the peer-to-peer message and channel message APIs is 500 calls per second.

• Messaging APIs

  The messaging time delay from the server to the client must be less than 200 ms, Agora recommends that you use the Signaling SDK for Linux to send messages from the server to the client.

  • Peer-to-peer message: Sends a peer-to-peer message from the server. The user who sends the message does not have to log in to Signaling.

  • Channel message: Sends a channel message from the server. You can send a message to a channel without joining it first.

  • Get message history: Retrieves historical messages from the specified channel. Returns messages based on timestamp range and message count parameters.

• Event APIs

  • User events: Gets user login and logout events from the Signaling server. Events are removed from the server once retrieved.

  • Channel events: Gets channel join and leave events from the Signaling server. Events are removed from the server once retrieved.

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

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.

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.

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

Primary domain name	Region domain name	Region
api.sd-rtn.com	api-us-west-1.sd-rtn.com	Western United States
	api-us-east-1.sd-rtn.com	Eastern United States
	api-ap-southeast-1.sd-rtn.com	Southeast Asia Pacific
	api-ap-northeast-1.sd-rtn.com	Northeast Asia Pacific
	api-eu-west-1.sd-rtn.com	Western Europe
	api-eu-central-1.sd-rtn.com	Central Europe
	api-cn-east-1.sd-rtn.com	East China
	api-cn-north-1.sd-rtn.com	North China
api.agora.io	api-us-west-1.agora.io	Western United States
	api-us-east-1.agora.io	Eastern United States
	api-ap-southeast-1.agora.io	Southeast Asia Pacific
	api-ap-northeast-1.agora.io	Northeast Asia Pacific
	api-eu-west-1.agora.io	Western Europe
	api-eu-central-1.agora.io	Central Europe
	api-cn-east-1.agora.io	East China
	api-cn-north-1.agora.io	North China