Sending Messages

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.

Breaking Change Notice - Page-level Subscription Messaging Feature Requirement

Starting April 30, 2019, a Page must be approved with the Page-level Subscription Messaging feature in order to use the Broadcast API. Apps were granted the subscription messaging permission at the app-level will no longer be respected. This change is in effect immediately to v3.3+ of the Graph API, and will apply to all lower versions on July 31, 2019.


Message Types

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.

Standard Messaging

When a person sends your bot a message or opts-in to receive messages via a web plug-in, your bot has up to 24 hours to respond. Your bot 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.

Subscription Messaging (beta)

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 your bot 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'.

Send API Basics

All messages are sent by submitting a POST request to the Send API with your page access token appended to the URL query string:<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>",
  "text":"hello, world!"

Content Types

The Messenger Platform supports sending many types of content in messages, including:

  • Text
  • Audio
  • Images
  • Video
  • Files

You can send all of these types of content as individual messages.

Messaging Types

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.

Breaking Change Update

To ease the transition to including the messaging_type property in all message sends, the Messenger Platform will automatically assign the following default properties when the messaging_type property is not included in the body of the request:

"messaging_type": "MESSAGE_TAG",
  • Messages using any of the airline templates will automatically be updated to include:
"messaging_type": "MESSAGE_TAG",
  • All other messages will automatically be updated to include:
"messaging_type": "RESPONSE"

Please note that any messages with the RESPONSE messaging type must be allowed under the 24+1 standard messaging policy.

While we have implemented these defaults to make the transition to messaging type easier, we strongly advise that all developers implement the messaging_type property for all message sends as soon as possible.

The following values for 'messaging_type' are supported:

Messaging TypeDescription


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.

Recipient IDs

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 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.

  • Phone number: If you know a user's phone number, you can specify recipient.phone_number in the API request. This will send a message request to the recipient, without requiring them to interact with your page first. Sending messages to phone numbers requires the pages_messaging_phone_number permission. For more information, see Customer Matching.

  • User Ref: For more information, see checkbox plugin.

Batching Requests

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.

Sending Text

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 '{
    "text":"hello, world!"

For a complete list of API calls and request properties, see the Send API Reference.

Sending Attachments

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:

  • URL
  • File
  • attachment_id

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.

Attachment Types

The Messenger Platform supports the following attachment types, specified in the attachment.type property of the message:

  • audio
  • video
  • image
  • file

Attaching from URL

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 '{

For a complete list of API calls and request properties, see the Send API Reference.

Attaching from File

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:

  • recipient: A JSON object identifying the message recipient.
  • message: A JSON object describing the message. Includes the asset type, and a payload. The payload is either empty, or sets the is_reusable property.
  • filedata:The location of the asset on your file system and MIME type.
curl  \
  -F 'recipient={"id":"<PSID>"}' \
  -F 'message={"attachment":{"type":"<ASSET_TYPE>", "payload":{"is_reusable"=true}}}' \
  -F 'filedata=@/tmp/shirt.png;type=image/png' \

For a complete list of API calls and request properties, see the Send API Reference.

Attaching Saved Assets

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 '{
        "attachment_id": "1745504518999123"

For a complete list of API calls and request properties, see the Send API Reference.

API Response

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 Limiting

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.

Best Practices

Text Messages

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.