Send a Message

To send messages to a person on Messenger or Instagram, the conversation must be initiated by that person. The Messenger Platform has several different types of messages you can send. Each message type has different policies and guidelines for what types of content and under what conditions they can be sent.

Message Components

All Send API requests from your app to send a message must include the following:

• The Page ID for the Facebook Page, or the Facebook Page linked to the Instagram Professional account, sending the message
• The ID for the person receiving the message
• A Page access token requested from the Page sending the message
• Permission from the person receiving the message
• The message type
• The message content

For more information about message components, visit the Send API Reference.

Standard Messaging Window

The Standard Messaging Window is the 24 hour time period in which you are allowed to send a message to a person. When a person sends your Page or Instagram Professional account a message or starts a conversation via a web plug-in, your app has up to 24 hours to send a message.

Messages sent within the 24 hour window may contain promotional content.

User Actions that Open the Standard Messaging Window

The following user actions open the 24 hour standard messaging window:

• A person sends a message to your Page or Instagram Professional account
• A person clicks a call-to-action button like Get Started within a conversation
• A person clicks on a Click-to-Messenger ad and then sends a message to your Page or Instagram Professional account
• A person sends a message to a Page via a plugin, such as the Send to Messenger or Checkbox plugin
• A person clicks on an m.me link that takes them to an existing conversation between the person and the Page
• A person clicks on an ig.me link that takes them to an existing conversation between the person and the Instagram Professional account
• A person reacts to a message, such as a marketing message
• A person comments on a post on your Page or Instagram Professional account
• A person publishes a visitor post on your Page

We know people expect a prompt response, therefore, we highly encourage you to respond as soon as possible within this 24 hour window. People have the option to block or mute a conversation at any time.

Recipient IDs

The ID for a person receiving the message is set in the recipient object parameter and can be one of the following ID types:

• Page-scoped ID (PSID) – An ID assigned to a person the first time the person sends a message to your Page. This unique ID represents interactions between your Page and the person.

• User Ref – An ID assigned to a person who used a plugin or postback button to send a message to your Page.

• Post or Comment ID: An ID assigned to a person who published a post on your Page or commented on a post. Used to send a Private Reply to the person.

Please note that user ID's from Facebook Login integrations are app-scoped and will not work with the Messenger platform.

Messaging Types

The type of message you are sending is set in the messaging_type parameter. This parameter is a more explicit way to ensure your messaging complies with messaging policies and the recipient's preferences.

The following types of messages are supported:

• Response – The message you are sending is a response to a received message. The message can contain promotional and non-promotional content and must be sent during the standard messaging window.

• Updates – The message you are sending is being sent proactively and is not in response to a received message. The message can contain promotional and non-promotional content and must be sent during the standard messaging window.

• Tagged Message – The message you are sending is being sent outside the standard messaging window. This message must include a message tag that matches the allowed use case for the tag and contains non-promotional content.

Message Tags

Message Tags allow you to send a message outside the standard messaging window. These messages are personally relevant updates for a person. For example, you may send updates about shipping and delivery, an upcoming reservation or flight, or alerts about a customer’s account. For messaging flows that require an escalation path, the Human Agent tag allows a business representative to manually respond to a person’s messages within a 7-day period.

Message Tags may not be used to send promotional content, including but not limited to: deals, offers, coupons, and discounts. Use of Message Tags outside the approved use cases may result in restrictions on the Page or Instagram account's ability to send messages. See the Messenger Platform and Instagram Messaging API Policy for details.

Businesses using Messenger Platform who want to send promotional messages outside the 24 hour standard messaging window should use Sponsored Messages or One-Time Notifications.

Content Types

The message you send may contain the following types of content:

Send a Basic Text

To send a basic text message to a person who sent your Page a message, send a POST request to the /PAGE-ID/messages endpoint, with the recipient object literal key id set to person's Page-scoped ID (PSID), the message_type parameter set to RESPONSE, and the message parameter object text set to the message text.

Sample Request

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"{PSID}"
  },
  "messaging_type": "RESPONSE",
  "message":{
    "text":"Hello, world!"
  }
}' "https://graph.facebook.com/v21.0/{PAGE-ID}/messages?access_token={PAGE-ACCESS-TOKEN}"
    

On success, your app will receive the following JSON response with the recipient's ID and the message ID.

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
} 

Send a Media Attachment

To send a message with media, such as a GIF or image, or a template, you add the content to the API request in a JSON message attachment object.

To send a message with an image to a person who sent your Page a message, send a POST request to the /PAGE-ID/messages endpoint, with the recipient object literal key id set to person's Page-scoped ID (PSID), the message_type parameter set to RESPONSE, and the message parameter attachment object type key set to image and the payload object url key set to the URL for the image.

Sample Request

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/v21.0/me/messages?access_token={PAGE_ACCESS_TOKEN}"
  

On success, your app will receive the followingn JSON response with the recipient's ID and the message ID.

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
} 

Sending audio, video or a file from a URL will use the same format.

You can also send media from your server or from content you have previously uploaded to a Meta server. Learn more about uploading files using the Attachment Upload API.

Best Practices

Text Messages

Attachments

More Message Types

Marketing Messages

Marketing Messages allows you to ask a person for permission to send multiple, marketing messages after the standard messaging window has ended. If the person accepts this request to receive these notifications, you will be able to send the person automated, recurring promotional messages with information about your upcoming sales or product releases and updates.

News Messaging (Under development)

News Messaging is only available for registered news publishers that are registered with the Facebook News Page Index (NPI). News Messaging allows news publishers to send non-promotional, news messages to people who have subscribed to receive these messages.

News messaging is not available for Instagram Messaging API.

One-time Notifications

One-time Notification allows you to ask a person for permission to send one follow-up message after the standard messaging window has ended. If the person accepts this request to receive a one time notification, you will be able to send a one message that is time-sensitive and personally relevant, such as an appointment reminder or back in stock alert.

One-Time Notifications are not available for Instagram Messaging API.

Private Replies

Private Replies allows you to send a message to a person when the person publishes a comment on one of your posts or ads, or publishes a visitor post on your Page or Instagram Professional account. The private reply can only be a single message, which will automatically include a link to the post or comment, and must be sent within seven days of the person publishing the post or comment.

Sponsored Messages

Sponsored Messages allow you to send promotional or non-promotional content, after the standard messaging window has expired, to a person who has previously sent a message to your Page or Instagram Professional account. Sponsored Messages appear like normal messages in the conversation but are annotated with the word Sponsored above the message. Sponsored message content must comply with advertising policies.

Sponsored Messages are not available for Instagram Messaging API.

Next Steps

Learn about the components you can add to messages in your conversations.

Learn More

Learn more about sending messages using the Messenger Platform.

• Attachment Upload API Reference – Learn more about uploading and sending media.
• Send API Reference – Learn more about all the tags, content, and attachments you can send.
• Rate Limits – Learn about the rate limits for sending messages using the Messenger Platform.