Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Android
iOS
macOS
Web
Linux C++
Unity

Messaging API

The messaging REST API enables you to send messages to a Signaling user or channel.

Authentication

To authenticate your messaging REST API requests, refer to the RESTful API authentication guidelines.

  • You can send peer-to-peer or channel messages with any user ID when using basic HTTP authentication.
  • When you use token authentication, you nay send peer-to-peer or channel messages with only the user ID you used to generate the Signaling token.

For more information about how to generate a Signaling token, see Secure authentication with tokens.

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.

Data format

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

  • Request: Refer to the examples in the following APIs.
  • 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.

Send peer-to-peer message API

  • Method: POST
  • Endpoint: /rtm/users/<user_id>/peer_messages

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

Call sequence

The following figures shows the process to send a peer-to-peer message from the server to the Signaling SDK with and without acknowledgement.

  • The receiver is online and wait_for_ack is true

  • wait_for_ack is false

Parameters

URL parameters

This API has the following URL parameters:

ParameterTypeDescription
user_idStringSignaling user ID to send a peer-to-peer message. It must not exceed 64 characters in length or be an empty string. This parameter supports the following characters:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character. (Not recommended): If the user ID contains a space, then the user ID cannot communicate with the Signaling SDK.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ",", "'"
As a URL parameter, the first character and the last character must not be a space.

Query parameters

This API has the following query parameters:

ParameterTypeDescription
wait_for_ackBoolean(Optional) Whether the API returns the HTTP response after the Signaling receives the ack response from the receiver to indicate that the message is received. The default is false.
  • true: The API returns the HTTP response after Signaling receives the ack response from the receiver to indicate that the message is received. The HTTP response contains message_delivered if successful.
  • false: The API returns the HTTP response immediately after Signaling receives the message. The HTTP response contains message_sent, if successful.

Request body parameters

This API has the following request body parameters:

ParameterTypeDescription
destinationStringSignaling user ID to receive a peer-to-peer message. It must not exceed 64 characters in length or be an empty string. This parameter supports the following characters:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character. (Not recommended): If the user ID contains a space, then the user ID cannot communicate with the Signaling SDK.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ",", "'"
enable_offline_messagingBoolean
caution
The offline message feature will be deprecated. Agora recommends that you do not use it.
(Optional) Whether to enable offline messages. The default is false.
  • true: Enable offline messages. If the receiver is offline when you send a peer-to-peer message, Signaling saves the message. The receiver will receive the message when online.Signaling saves a maximum of 200 offline messages for each receiver. When the number of saved offline messages exceeds the maximum limit, the latest message replaces the earliest message.
  • false: Disable offline messages.
enable_historical_messagingBooleanWhether to save as a historical message. The default value is false.
  • true: Save as historical messages. You can use the historical message RESTful API to query historical messages.
  • false:Do not save as historical messages.
payloadStringContent of the peer-to-peer message. It must not be an empty string or exceed 32 KB in length.

Response body parameters

This API has the following response body parameters:

ParameterTypeDescription
resultStringRequest result.
  • success: The request succeeds.
  • failed: The request fails.
request_idStringUnique ID to identify this request.
codeStringMessage status.
  • message_sent: The message is sent.
  • message_delivered: The message is received.
  • message_offline: The receiver is offline.

Request example

  • Request URL:

    _1
    https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/peer_messages?wait_for_ack=true

  • Content-type: application/json;charset=utf-8
  • Authorization: Basic HTTP or token.
  • Request body:

    _6
    {
    _6
    "destination": "userB",
    _6
    "enable_offline_messaging": false,
    _6
    "enable_historical_messaging": false,
    _6
    "payload": "Hello"
    _6
    }

Response example

  • The message has been sent:


    _5
    {
    _5
    "result": "success",
    _5
    "request_id": "123",
    _5
    "code": "message_sent"
    _5
    }

  • The message has been received:


    _5
    {
    _5
    "result": "success",
    _5
    "request_id": "123",
    _5
    "code": "message_delivered"
    _5
    }

  • The receiver is offline:


    _4
    {
    _4
    "request_id": "123",
    _4
    "code": "message_offline"
    _4
    }

Send channel message API

  • Method: POST
  • Endpoint: /rtm/users/<user_id>/channel_messages

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

Parameters

URL parameters

This API has the following URL parameters:

ParameterTypeDescription
user_idStringSignaling user ID to send a channel message. It must not exceed 64 characters in length or be an empty string. This parameter supports the following characters:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character. (Not recommended): If the user ID contains a space, then the user ID cannot communicate with the Signaling SDK.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ",", "'"
info
As a URL parameter, the first character and the last character must not be a space.

Request body parameters

This API has the following request body parameters:

ParameterTypeDescription
channel_nameStringSignaling channel name to receive a channel message. It must not exceed 64 characters in length or be an empty string. This parameter supports the following characters:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character. (Not recommended): If the channel name contains a space, then the API cannot communicate with the Signaling SDK.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " , ", "|", "~", ",", "'"
payloadStringContent of the channel message. It must not be an empty string or exceed 32 KB in length.

Response body parameters

This API has the following response body parameters:

ParameterTypeDescription
codeStringMessage status.
  • message_sent: The message is sent.
  • request_idStringUnique ID to identify this request.
    resultStringRequest result.
    • success: The request succeeds.
    • failed: The request fails.

    Request example

    • Request URL

      _1
      https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/channel_messages

    • Content-type: application/json;charset=utf-8
    • Authorization: Basic HTTP or token.
    • Request body:

      _5
      {
      _5
      "channel_name":"channelA",
      _5
      "enable_historical_messaging": false,
      _5
      "payload": "Hello"
      _5
      }

    Response example


    _5
    {
    _5
    "code": "message_sent",
    _5
    "request_id": "123",
    _5
    "result": "success"
    _5
    }

    Status codes

    Status codeDescription
    200The request is successful.
    400The request parameters are incorrect. Please check the parameters per the error message.
    401User authentication error.
    408No response from the server or the request times out. Please try again later.
    429Too many requests.
    500Internal server error.

    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

    Signaling