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.
On August 29th, 2019 we announced updates to the policy to remove the “+1” of the 24+1 Policy starting January 15, 2020.
When a person sends your Page a message or opts-in to receive messages via a web plug-in, your app has up to 24 hours to respond. Your app may send one additional message after the 24-hour time limit has expired. This is commonly referred to as the '24 + 1 policy'. Messages can be sent outside the 24-hour window for specific use cases with message tags.
On August 29th, 2019 we announced updates to Message Tags on the Messenger Platform. The newly introduced tags are now available. The current message tags will be supported until January 15, 2020.
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.
On August 29, 2019 we announced that, effective January 15, 2020, we will no longer support subscription messaging for pages that are not registered and approved as News Publishers via the News Page Index (NPI). We encourage relevant Pages to apply for NPI sooner to allow sufficient time for review and approval.
Subscription messaging allows your Page to send recurring messages for specific use cases that are not subject to the 24-hour standard messaging window.
A Page admin must apply for page-level permission to send subscription messages. If your Page has subscription messaging permission, users automatically opt-in to receive subscription messages when they start a conversation; however, it is highly recommended that ask permission to send subscription messages to ensure a positive user experience.
Sponsored messaging is a type of ad that sends a message directly to all conversations currently open with your bot or to a custom list of PSIDs that currently have open conversations with your bot. 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/v5.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 ensure bots are complying 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 or under the 24+1 policy. 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 or under the 24+1 policy. |
| 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 bot a message or interacts with your bot 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: For more information, see checkbox plugin.
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/v5.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. Max attachment size is 25MB. 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/v5.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/v5.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/v5.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 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": "1008372609250235",
"message_id": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}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.
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.