Signaling Overview

The Signaling 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.

API basics

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.

REST APIs

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.

• Send 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.
• Send 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

• Get user events: Gets user login and logout events from the Signaling server. Events are removed from the server once retrieved.
• Get channel events: Gets channel join and leave events from the Signaling server. Events are removed from the server once retrieved.

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.

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

   • If the DNS address of the service server is located outside 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 REST API request using the primary domain fails, use the following retry strategy:

   • Primary domain retry: Retry using the same primary domain name.
   • 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.
   • Adjacent domain retry: If alternate domain retry fails, retry using a regional 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 to Germany. Germany is in Central Europe, corresponding to api-eu-central-1.agora.io. The adjacent region is Western Europe, so you can retry using api-eu-west-1.agora.io or api-eu-west-1.sd-rtn.com.

Precautions

• To avoid exceeding the QPS limit with retry requests, use a backoff strategy. For example, wait 1 second before the first retry, 3 seconds before the second retry, and 6 seconds before the third retry.
• If the request fails because of a network problem rather than DNS resolution, skip alternate domain retry and proceed to adjacent domain retry.
• Before switching to a regional domain name, make sure the REST service you call is deployed in that region.

Domain name table