When your Facebook app is in Development Mode, the Send API will only work for admins, developers and testers of the app.
After your bot is approved for the pages_messaging permission and public, it will work for the general public.
The Send API is the main API used to send messages to users, including text, attachments, structured message templates, sender actions, and more.
messaging_type Property Required (Effective May 7, 2018)As of the release of Messenger Platform v2.2, we are requesting developers to include the messaging_type property in all message sends.
Beginning May 7, 2018, this property will be required for all message sends. After this date, message sends that do not include messaging_type will return an error and not be delivered.
For more information on the messaging_type property, see Sending Messages - Messaging Types below.
As of the release of Messenger Platform v2.3, permission to send subscription messages will be granted at the Page-level rather than at the app-level.
As we continue to review our Subscription Messaging policies, developers provided access to send messages via app-level permissions may continue to do so until further notice. We highly encourage developers to migrate to the Page-level permission as soon as possible as we evaluate potential updates to this policy.
For more information on handling this transition, see Messaging Transitioning from App-level to Page-level Subscription Messaging
For error codes and their meanings, refer to this page.
https://graph.facebook.com/v2.6/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/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
The Graph API version should be set to 2.6 or greater.
| 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 id, phone_number, or user_ref.
| Property | Type | Description |
|---|---|---|
| String | Either |
| String | Optional. Phone number of the recipient with the format +1(212)555-2368. Your bot must be approved for Customer Matching to send messages this way. |
| String | Optional. |
| Object | Optional. Used only if {"first_name":"John", "last_name":"Doe"}Providing a name increases the odds of a successful match. |
The id must be an ID that was retrieved through the Messenger entry points or through the Messenger webhooks (e.g., a person may discover your business in Messenger and start a conversation from there.
These IDs are page-scoped IDs (PSID). This means that the IDs are unique for a given page.
If you have an existing Facebook Login integration, user IDs are app-scoped and will not work with the Messenger platform.
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.
Effective February 20, 2018, the Send API no longer includes 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": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}
| Property Name | Description |
|---|---|
| Unique ID for the user |
| Unique ID for the message |
Messenger Platform supports a high rate of calls to the Send API.
However, you should architect your system such that you distribute any sudden high amounts of load over time and are able to control your throughput should you hit our rate limits.
Rate limits are in place to prevent malicious behavior and poor user experiences.
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 an exceptionally high volume of messaging activities 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). Once a Page crosses that threshold and becomes a high-MPS Page, certain messaging features will be limited in Messenger. Even if the volume drops thereafter, the status won't be reverted. High-MPS Pages are expected to handle their messaging exclusively through the API.