# Signaling Overview (/en/api-reference/api-ref/signaling)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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 [#api-basics]

All requests are sent to the host `api.agora.io`. See [Ensure service reliability](#ensure-service-reliability) for alternate domain names.

* **Authentication**: All APIs require [Basic Auth](authentication) for authentication.
* **Request**: Refer to the respective API examples.
* **Response**: The response content is in JSON format.
* **Base URL**:

  ```text
  https://api.agora.io/dev/v2/project/<appid>
  ```

  where `<appid>` is the Agora app ID for your project.

<CalloutContainer type="info">
  <CalloutDescription>
    - 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.
  </CalloutDescription>
</CalloutContainer>

## REST APIs [#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](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](channel-message): Sends a channel message from the server. You can send a message to a channel without joining it first.
* [Get message history](message-history): Retrieves historical messages from the specified channel. Returns messages based on timestamp range and message count parameters.

**Event APIs**

* [Get user events](user-events): Gets user login and logout events from the Signaling server. Events are removed from the server once retrieved.
* [Get channel events](channel-events): Gets channel join and leave events from the Signaling server. Events are removed from the server once retrieved.

## Ensure service reliability [#ensure-service-reliability]

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

### Switch the domain name [#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 [#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 [#domain-name-table]

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