The Send API is the main API used to send messages to users, including text, attachments, structured message templates, sender actions, and more.
A page access token with pages_messaging permission is required to interact with this endpoint.
Apps in Development Mode, are restricted to message people that have a role in the app. Additionally Pages in unpublished status will only be allowed to message people with a role on the Page.
For error codes and their meanings, refer to this page.
https://graph.facebook.com/v4.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>
curl -X POST -H "Content-Type: application/json" -d '{
"messaging_type": "<MESSAGING_TYPE>",
"recipient": {
"id": "<PSID>"
},
"message": {
"text": "hello, world!"
}
}' "https://graph.facebook.com/v4.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
| Property | Type | Description |
|---|---|---|
| String | The messaging type of the message being sent. For supported types and more information, see Sending Messages - Messaging Types |
| Object |
|
| Object |
|
| String | Message state to display to the user:
Cannot be sent with When using |
| String | Optional. Push notification type:
Defaults to |
| String | Optional. The message tag string. See Message Tags. |
recipientDescription of the message recipient. All requests must include one of the following properties to identify the recipient.
| Property | Type | Description |
|---|---|---|
| String | Page Scoped User ID (PSID) of the message recipient. The user needs to have interacted with any of the Messenger entry points in order to opt-in into messaging with the Page. Note that Facebook Login integrations return user IDs are app-scoped and will not work with the Messenger platform. |
| String | Used for the checkbox plugin. |
| String | Used for Private Replies to reference the visitor post to reply to. |
| String | Used for Private Replies to reference the post comment to reply to. |
message| Property | Type | Description |
|---|---|---|
| String | Message text. Previews will not be shown for the URLs in this field. Use attachment instead. Must be UTF-8 and has a 2000 character limit. |
| Object |
|
| Array< | Optional. Array of |
| String | Optional. Custom string that is delivered as a message echo. 1000 character limit. |
attachment objectThe following can be included in the attachment object:
| Property | Type | Description |
|---|---|---|
| String | Type of attachment, may be |
| Object | Payload of attachment |
A successful Send API request returns a JSON string containing identifiers for the message and its recipient.
Note that the Send API will not recipient_id in the response for message sends that use recipient.user_ref or recipient.phone_number to identify the message recipient.
{
"recipient_id": "1254477777772919",
"message_id": "AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}
| Property Name | Description |
|---|---|
| Unique ID for the user |
| Unique ID for the message |
Rate limits are in place to prevent malicious behavior and poor user experiences.
The per day rate limit is equal to 200 * the number of people the business can message via Messenger.
For easy debugging of the actual rate limit that applies to the page, see page_messages_total_messaging_connections
For pages with large audiences, we recommend a send rate of 250 requests per second.
You should architect your system to distribute any sudden high amounts of load over time and are able to control your throughput should you hit our rate limits.
Be sure to catch any errors returned by the Send API including the one indicating that you've reached the rate limit.
When a Page experiences high volume of messages over a short period of time or is constantly sending or receiving messages with a large number of threads concurrently, it can trigger our system and change it into a high-MPS Page (messages per second). See Pages with High Volume Messages