Send peer-to-peer message
Updated
Sends a peer-to-peer Signaling message from the server.
https://api.agora.io/dev/v2/project/{appid}/rtm/users/{user_id}/peer_messagesSends 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.
Path Parameters
The App ID of your Agora project.
Signaling user ID to send a peer-to-peer message. It must not exceed 64 characters in length or be an empty string. Since user_id is a URL parameter, the first and last characters must not be a space.
Note
Since user_id is a URL parameter, the first character and the last characters must not be a space.
Query Parameters
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. -
false: The API returns the HTTP response immediately after the Agora RTM server receives the message, without waiting for receiver acknowledgement.
falseRequest
For more information about how to generate a Signaling token, see Secure authentication with tokens.
Request Body
application/json
Signaling user ID to receive a peer-to-peer message. It must not exceed 64 characters in length or be an empty string.
Whether to enable offline messages.
true: Enable offline messages. If the receiver is offline when you send a peer-to-peer message, Signaling saves the message (maximum 200 per receiver) and delivers it when the receiver is online.false: Disable 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.
falseWhether to save as a historical message.
true: Save as a historical message.false: Do not save as a historical message.
falseContent of the peer-to-peer message. It must not be an empty string or exceed 32 KB in length.
Response
-
If the returned status code is
200, the request was successful. The response body contains the result of the request. -
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.
Response Body
application/json
Response schema
200application/jsonThe request was successful. The response body contains the result of the request.
Request result. success if the request succeeds, failed if it fails.
Request result.
- success: The request succeeds.
- failed: The request fails.
Unique ID to identify this request.
Message status: message_sent, message_delivered, or message_offline.
Message status.
- message_sent: The message is sent.
- message_delivered: The message is received.
- message_offline: The receiver is offline.
defaultapplication/jsonThe request failed. The response body includes the error code and description.
Request examples
curl -X POST 'https://api.agora.io/dev/v2/project/876922cbca0098dff4323566daa89675/rtm/users/userA/peer_messages?wait_for_ack=true' \ -H 'Content-Type: application/json;charset=utf-8' \ -H 'Authorization: Basic <your_base64_encoded_credentials>' \ -d '{ "destination": "userB", "enable_offline_messaging": false, "enable_historical_messaging": false, "payload": "Hello" }'Response example
{ "result": "success", "request_id": "123", "code": "message_sent"}