Many types of unstructured content can be sent with the Messenger Platform, including text, audio, images, video, and files.
There are also a number of pre-defined message templates available that allow you to send structured messages for a richer experience. For more information, see Templates.
For a complete list of API calls and request properties, see the Send API Reference.
To send messages to someone on Messenger, the conversation must be initiated by the user. Messages sent with the Messenger Platform are classified as one of three different message types. Each message type has different policies and guidelines for what types of content and under what conditions they can be sent.
The following is a brief overview of each message type. For more details, see the Messenger Platform Policy Overview.
When a person sends your Page a message or starts a conversation via a web plug-in, your app has up to 24 hours to respond. Messages can be sent outside the 24-hour window for specific use cases with message tags.
One-time Notification allows a Page to get a one message opt in from a person to send a follow-up message after 24-hour messaging window have ended.
When a person creates Post Comments or Visitor Posts on your Page then, Private Replies allows the Page to send a message on Messenger.
Message Tags enable businesses to send important and personally relevant 1:1 updates to users outside the 24 hour Standard messaging window for a set of approved use cases. For example, you may send updates about shipping and delivery, an upcoming reservation or flight, or alerts about a customer’s account.
News messages allow news publishers to send regular news updates to their subscribers in Messenger. This feature is only available for registered news Pages under the Facebook News Page Index (NPI)
Sponsored messages allow you to reengage open conversation in Messenger outside the Standard Messaging window. Sponsored Messages appear like normal messages in the conversation but are marked 'Sponsored'.
All messages are sent by submitting a POST request to the Send API with your page access token appended to the URL query string:
https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>
The body of the HTTP request is sent in JSON format and requires three properties:
messaging_type: Identifies the purpose of the message send.recipient: Identifies the intended recipient of the message.message: Defines the message to be sent.Here's a simple example of the body of a request to send a text message:
"messaging_type": "<MESSAGING_TYPE>",
"recipient":{
"id":"<PSID>"
},
"message":{
"text":"hello, world!"
}
The Messenger Platform supports sending many types of content in messages, including:
You can send all of these types of content as individual messages.
The messaging_type property identifies the messaging type of the message being sent, and is a more explicit way to messaging complies with policies for specific messaging types and respecting people's preferences.
The following values for 'messaging_type' are supported:
| Messaging Type | Description |
|---|---|
| Message is in response to a received message. This includes promotional and non-promotional messages sent inside the 24-hour standard messaging window. For example, use this tag to respond if a person asks for a reservation confirmation or an status update. |
| Message is being sent proactively and is not in response to a received message. This includes promotional and non-promotional messages sent inside the the 24-hour standard messaging window. |
| Message is non-promotional and is being sent outside the 24-hour standard messaging window with a message tag. The message must match the allowed use case for the tag. |
Any time you send a message, you must identify the message recipient in the body of the request. The Messenger Platform supports two ways to identify message recipients:
Page-scoped ID (PSID): Any time someone sends your Page a message or interacts with your Page in Messenger for the first time, the sender's page-scoped ID will be included in the sender.id property of the event. The PSID is unique for a given page. Please note that user ID's from Facebook Login integrations are app-scoped and will not work with the Messenger platform.
User Ref: Special case, used to reference the user in the context of the Checkbox Plugin.
Post of Comment ID: Special case, used to reference the user in the context of Private Replies.
The Graph API supports request batching, which allows you to send up to 50 messages with a single API request. Each request in a batch is counted toward the Send API rate limit. For more information, see Making Multiple Requests.
To send a basic text message, submit a POST request to the Send API, with message.text set in the request body:
curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"<PSID>"
},
"message":{
"text":"hello, world!"
}
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
For a complete list of API calls and request properties, see the Send API Reference.
The Messenger Platform allows you to attach assets to messages, including audio, video, images, and files. The maximum attachment size is 25 MB. The maximum resolution for images is 85 Megapixel. There are three ways to attach an asset to a message:
Please note that our servers might encode an uploaded file to ensure compatibility. It's possible to get a file size limit error if the resulting size surpasses the 25MB limit.
The Messenger Platform supports the following attachment types, specified in the attachment.type property of the message:
To send an attachment from a URL, submit a POST request to the Send API, with message.attachment set in the request body. The attachment object includes the asset type (image, audio, video, or file), and a payload that includes the asset url:
curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"1254459154682919"
},
"message":{
"attachment":{
"type":"image",
"payload":{
"url":"http://www.messenger-rocks.com/image.jpg",
"is_reusable":true
}
}
}
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
For a complete list of API calls and request properties, see the Send API Reference.
To send an attachment from file, submit a POST request to the Send API with the message details as form data, with the following fields:
is_reusable property.
curl \
-F 'recipient={"id":"<PSID>"}' \
-F 'message={"attachment":{"type":"<ASSET_TYPE>", "payload":{"is_reusable":true}}}' \
-F 'filedata=@/tmp/shirt.png;type=image/png' \
"https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
For a complete list of API calls and request properties, see the Send API Reference.
The Messenger Platform supports saving assets via the Send API and Attachment Upload API. This allows you reuse assets, rather than uploading them every time they are needed. For information on saving assets, see Saving Assets.
To attach a saved asset to a message, specify the attachment_id of the asset in the payload.attachment_id property of the message request:
Only attachments that were uploaded with the is_reusable property set to true can be sent to other message recipients.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"1254459154682919"
},
"message":{
"attachment":{
"type":"image",
"payload":{
"attachment_id": "1745504518999123"
}
}
}
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
For a complete list of API calls and request properties, see the Send API Reference.
A successful Send API request to a PSID returns a JSON string containing identifiers for the message and its recipient.
Note that the Send API does not include recipient_id in the response for messages sent using recipient.user_ref or recipient.phone_number to identify the message recipient.
{
"recipient_id": "1008372609250235",
"message_id": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}Page Rate limits are in place to prevent malicious behavior and poor user experiences. Messenger API calls beyond the rate limit below will fail with error code 613.
Calls within 24 hours = 200 * Total Messenger AudienceSince the rate limit is based on the Page audience, it is possible for the same app to hit the rate limit for one Page and not another. 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.
Keep it short. Consider screen size and scrolling behavior; compact messages are easier for people to follow. Try sending a few separate messages instead of one long one.
Don't use text as a substitute for images, tables, charts, and images. Structured messages or even a webview might suit your needs better.
Don't write lengthy exchanges. If you need to communicate multiple things, try sending a few separate messages instead of one long one.
Pay attention to quality. Use colorful images with high resolution to make your messages stand out.
Consider aspect ratio. Review how your image may get cropped when it appears in the message bubble.
Don't put large amounts of text in your image. Use a text message instead, or combine images and text with a generic template.