Send peer-to-peer message

Send peer-to-peer message

POST

https://api.agora.io/dev/v2/project/<appid>/rtm/users/<user_id>/peer_messages

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

• You can send peer-to-peer or channel messages with any user ID when using basic HTTP authentication.
• When you use token authentication, you may send peer-to-peer or channel messages using 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.

appId stringrequired

The App ID of your Agora project.

user_id stringrequired

Signaling 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-z.
• All uppercase English letters: A-Z.
• All numeric characters: 0-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

Since user_id is a URL parameter, the first character and the last characters must not be a space.

wait_for_ack booleannullable

Default: false

Whether the API returns the HTTP response after Signaling receives the acknowledgement from the receiver.

• true: The API waits for the receiver to acknowledge receipt of the message before returning the HTTP response. The process involves:
  1. App server sends the peer-to-peer message API.
  2. Agora RTM server forwards the message to the Agora RTM SDK.
  3. SDK sends an ACK back to the server.
  4. Server returns message_delivered to the app server.
• false: The API returns the HTTP response immediately after Agora RTM server receives the message, without waiting for receiver acknowledgement. The server returns message_sent to the app server.

APPLICATION/JSON

BODYrequired

• destination stringrequired

  Signaling 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-z.
  • All uppercase English letters: A-Z.
  • All numeric characters: 0-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 booleannullable

  Default: false

  Whether to enable offline messages.

  caution

  The offline message feature is deprecated and will be removed in a future version. Agora recommends that you do not use it.

  • true: Enable offline messages. If the receiver is offline when you send a peer-to-peer message, Signaling saves the message. The receiver receives 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_messaging booleannullable

  Default: false

  Whether to save as a historical message.

  • true: Save as a historical message. You can use the historical message RESTful API to query historical messages.
  • false: Do not save as a historical message.
• payload stringrequired

  Content of the peer-to-peer message. It must not be an empty string or exceed 32 KB in length.

• If the returned status code is 200, the request was successful. The response body contains the result of the request.

OK

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

• If the returned status code is not 200, the request failed. The response body includes the error code and description. Refer to status codes to understand the possible reasons for failure.

Authorization

This endpoint requires Basic Auth.

Request example

• curl
• Python
• Node.js

_9

curl -X POST 'https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/peer_messages?wait_for_ack=true' \

_9

-H 'Content-Type: application/json;charset=utf-8' \

_9

-H 'Authorization: Basic <your_base64_encoded_credentials>' \

_9

-d '{

_9

"destination": "userB",

_9

"enable_offline_messaging": false,

_9

"enable_historical_messaging": false,

_9

"payload": "Hello"

_9

}'

Response examples

• Message sent
• Message delivered
• Receiver offline

_5

{

_5

"result": "success",

_5

"request_id": "123",

_5

"code": "message_sent"

_5

}