通知
RTM 1.x 将于近期下架，各版本退休日期和替代方案详见 退休政策 。
Documentation
Real-time Messaging
Console 官网 Community Technical support
English
search-icon

Messaging RESTful API

Last updated 2022/07/14 03:27:46

Authentication

For basic HTTP authentication, you can send peer-to-peer or channel messages with any user ID. For token authentication, you can send peer-to-peer or channel messages with only the user ID used to generate the RTM token.
If the messaging time delay from the server to the client must be less than 200 ms, Agora recommends that you use the RTM Linux C++ SDK or the RTM Linux Java SDK to send messages from the server to the client.

Basic authentication

You need to pass the basic HTTP authentication and put `api_key:api_secret` in the `Authorization` field of the HTTP header. For more information on how to generate the Authorization field, see RESTful API authentication.

Token authentication

If you have already generated an RTM Token on your server, you can use token authentication. You need to put the following information to the x-agora-token field and the x-agora-uid field when sending your HTTP request:

  • The RTM Token generated at your server.
  • The uid you used to generate the RTM Token.

Sample code

The following sample code shows how to implement token authentication in Java:

Request request = new Request.Builder()
...
// Puts your RTM Token to the `x-agora-token` field of the HTTP request.
.addHeader("x-agora-token", "<Your RTM Token>")
// Puts the uid, which generates the RTM token, to the `x-agora-uid` field of the HTTP request.
.addHeader("x-agora-uid", "<Your uid used to generate the RTM Token>")
...
For more information about how to generate an RTM Token, see Token Security.

Data format

All requests are sent to the host: api.agora.io.

If a RTM RESTful API request to api.agora.io fails, refer to Use dual domain names.
  • Request: See the examples in the following APIs.
  • Response: The response content is in JSON format.
  • Base URL: https://api.agora.io/dev/v2/project/<appid>
<appid> is the App ID used by your project. All the request URLs and request bodies are case-sensitive.

Sends peer-to-peer message API (POST)

  • Method: POST
  • Access point: /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 the RTM system.

Call limit

For each app ID, the maximum combined frequency of the Sends peer-to-peer message API and the Sends channel message API is 500 calls per second.

Call sequence

The following figure shows the process in which the server sends a peer-to-peer message to the Agora RTM SDK.

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:

Parameter Type Description
user_id String RTM user ID to send a peer-to-peer message. Must not exceed 64 characters in length and not 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:

Parameter Type Description
wait_for_ack Boolean (Optional) Whether the API returns the HTTP response after the Agora RTM server 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 the Agora RTM server 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 the Agora RTM server receives the message. The HTTP response contains "message sent" if successful.

Request body parameters

This API has the following request body parameters:

Parameter Type Description
destination String RTM user ID to receive a peer-to-peer message. Must not exceed 64 characters in length and not 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_messaging Boolean
The offline message feature is deprecated since RTM SDK v1.5.0 for all platforms. In previous versions, users who integrate this feature can still 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, the RTM server saves the message. The receiver will receive the message when online.The RTM server 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_messaging Boolean Whether 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.
payload String Content of the peer-to-peer message. Must not be an empty string and not exceed 32 KB in length.

Response body parameters

This API has the following response body parameters:

Parameter Type Description
result String Request result.
  • "success": The request succeeds.
  • "failed": The request fails.
request_id String Unique ID to identify this request.
code String Message status.
  • "message_sent": The message is sent.
  • "message_delivered": The message is received.
  • "message_offline": The receiver is offline.

Request example

  • Request URL:

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

  • Content-type is application/json;charset=utf-8

  • Authorization is basic HTTP or token. See RESTful API Authentication.

  • Request body:

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

Response example

The message has been sent:

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

The message has been received:

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

The receiver is offline:

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

Sends channel message API (POST)

  • Method: POST
  • Access point: /rtm/users/<user_id>/channel_messages

Sends a channel message from the server. The user who sends the message does not have to join the channel.

Call limit

For each app ID, the maximum combined frequency of the Sends peer-to-peer message API and the Sends channel message API is 500 calls per second.

Parameters

URL parameters

This API has the following URL parameters:

Parameter Type Description
user_id String RTM user ID to send a channel message. Must not exceed 64 characters in length and not 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.

Request body parameters

This API has the following request body parameters:

Parameter Type Description
channel_name String RTM channel name to receive a channel message. Must not exceed 64 characters in length and not 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: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".","'"
payload String Content of the channel message. Must not be an empty string and not exceed 32 KB in length.

Response body parameters

This API has the following response body parameters:

Parameter Type Description
code String Message status.
  • "message_sent": The message is sent.
    		•
    request_id String Unique ID to identify this request.
    result String Request result.
    • "success": The request succeeds.
    • "failed": The request fails.

    Request example

    • Request URL

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

    • Content-type is application/json;charset=utf-8

    • Authorization is basic HTTP or token. See RESTful API Authentication.

    • Request body:

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

    Response example

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

    Status code

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