Send a Message

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.

Message Types

Your app can send unstructured or structured messages. An unstructured message can include text, audio, images, video, and files. A structure message will use one of our message templates that can include buttons, products, receipts, and more.

Standard Messaging

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.

  • Standard Messaging - Businesses will have up to 24 hours to respond to a user. Messages sent within the 24 hour window may contain promotional content. We know people expect businesses to respond quickly, and businesses that respond to users in a timely manner achieve better outcomes. We highly encourage businesses to respond to people’s messages as soon as possible.

Businesses will have up to 24 hours to respond to a user. Messages sent within the 24 hour window may contain promotional content. Users have the option to block or mute a conversation with a business at any time.

Here are examples of the user actions that open the 24 hour Standard Messaging window on Messenger Platform:

  • User sends a message to the Page
  • User clicks a call-to-action button like Get Started within a Messenger conversation
  • User clicks on a Click-to-Messenger ad and then starts a conversation with the Page
  • User starts a conversation with a Page via a plugin, such as Send to Messenger plugin or the Checkbox plugin.
  • User clicks on an m.me link with a ref parameter on an existing thread
  • User reacts to a message. See Replies and Reactions

For information on how you may be able to send messages outside the 24-hour messaging window, see Message Tags, and Sponsored Messages.

One-time Notification

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.

  • One-time Notification - Enable businesses to request a user to send one follow-up message after the 24-hour messaging window has ended. Learn more here. One-Time Notifications are not available for IG Messaging API.

Messenger Platform's One-Time Notification API (Beta) allows a page to send a time-sensitive and personally relevant notification for use cases (e.g. back in stock alert) where someone has explicitly requested to receive a one-time follow up message. Once the user asks to be notified, the page will receive a token which is an equivalent to a permission to send a single message to the user. The token can only be used once and will expire within 1 year of creation. Learn more here. Note, One-Time Notification is not available for IG Messaging API.

Private Replies

When a person creates Post Comments or Visitor Posts on your Page then, Private Replies allows the Page to send a message on Messenger.

When users create a Post Comment or a Visitor Posts on a Page, Private Replies allows the Page to send a single message as a reply using Messenger Platform. Private replies are currently allowed within 7 days of the referenced user action. Along with the message sent, the user will also receive a reference to their Post Comment or Visitor Posts. For Private Replies using Instagram Messaging API, see Private Replies.

Recurring Notifications

Recurring Notifications This feature allows Pages to send Recurring Notifications on a topic, and a frequency, a user has opted-in to. Recurring Notifications are a great way for Pages to build relationships with customers and keep them apprised of updates.

Message Tags

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.

  • Message Tags - Enable businesses to send important and personally relevant 1:1 updates to users outside the 24 hour Standard messaging window. We provide a number of Message Tags to support certain use cases. Some Tags are available on both Messenger Platform and IG Messaging API, while others are applicable only to Messenger Platform. The Message Tags include a Human Agent tag that allows businesses to manually respond to user messages within a 7-day period. Learn more here.

Message Tags enable sending important and personally relevant updates to users outside the 24-hour Standard messaging window, for a set of approved use cases. For complete details on allowed use cases, see the list of supported Message Tags. Use of tags outside of approved use cases may result in restrictions on your ability to send messages. Please note, some Message Tags are available only for Messenger Platform and not IG Messaging API.

News Messaging (beta)

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)

  • News messaging - Only Pages that are registered with the News Page Index (NPI) will be allowed to send non-promotional news messages. Note that News messaging is not available for IG Messaging API.

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 News Page Index (NPI) and is not available for Instagram Messaging API. Pages registered with the News Page Index don’t need to apply for news messaging permission.

News messaging apply to news content only, and must not be used for promotional content, including but not limited to subscription offers, deals, coupons, discounts or content produced by or that promotes a third party (e.g., branded content, affiliate marketing). To send news messages, NPI registered pages need to use the NON_PROMOTIONAL_SUBSCRIPTION message tag. Use of news messaging outside of these approved use cases may result in restrictions on your ability to send news messages.

Note that News messaging is not available for IG Messaging API.

Sponsored Messages

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

  • Sponsored Messages - Sponsored messages allow businesses to send promotional content outside the standard messaging window. Sponsored Messages are not available for IG Messaging API.

Sponsored Messages allow businesses to reengage with people who have an open conversation with their Page in Messenger. Sponsored Messages can be sent outside the 24 hour standard messaging window and can include both promotional and non-promotional content. Sponsored messages are annotated in the conversation with the word 'Sponsored' above the message.

Sponsored message content must comply with advertising policies. For more information on sending sponsored messages, see Sponsored messages.

Please note, Sponsored Messages are not available for IG Messaging API.

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:

https://graph.facebook.com/v14.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!"
}

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 messaging complies with policies for specific messaging types and respecting people's preferences.

The following values for 'messaging_type' are supported:

Messaging TypeDescription

RESPONSE

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.

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_TAG

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

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 '{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "text":"hello, world!"
  }
}' "https://graph.facebook.com/v14.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

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

  • 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
  • template. For more info on this type, see Templates

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 '{
  "recipient":{
    "id":"1254459154682919"
  },
  "message":{
    "attachment":{
      "type":"image", 
      "payload":{
        "url":"http://www.messenger-rocks.com/image.jpg", 
        "is_reusable":true
      }
    }
  }
}' "https://graph.facebook.com/v14.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
  

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' \
  "https://graph.facebook.com/v14.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"  
  

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 --location --request POST 'https://graph.facebook.com/v2.10/me/message_attachments?access_token=<PAGE_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "recipient":{
    "id":"1254459154682919"
  },
  "message":{
    "attachment":{
      "type":"image", 
      "payload":{
        "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 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"
}

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.

Attachments

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.

Learn More

Check the Meta Platform Dashboard for connectivity issues to see if there is an outage or known issue. Meta Status Tool

Messenger Platform Developer's Support Page Support for Developers: Engineering, Business and Ads Management, App Compliance, Personal Account

Support Resources for the Messenger Platform Community Resources, Developer Docs and Tools, Support Tools