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.
On July 23, 2024 we launched the new Instagram API with Instagram Login. An Instagram professional account – Business or Creator account – will no longer need to be linked to a Facebook Page in order to have conversations with customers, followers, or Instagram users interested in their business or Instagram account, manage comments, or publish media. Learn more about this new version in our blog post.
When required by applicable law, automated chat experiences must disclose that a person is interacting with an automated service:
Automated chat experiences that serve the following groups should pay special attention to this requirement:
Disclosures may include but are not limited to: “I’m the [Page Name] bot,”“You are interacting with an automated experience,” “You are talking to a bot,” or “I am an automated chatbot.”
Even where not legally required, we recommend informing users when they’re interacting with an automated chat as best practice, as this helps manage user expectations about their interaction with your messaging experience.
Visit our
Developer Policies
for more information.
All Send API requests from your app to send a message must include the following:
For more information about message components, visit the
Send API Reference.
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:
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.
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.
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 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.
The message you send may contain the following types of content:
|
|
|
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.
curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"{PSID}"
},
"messaging_type": "RESPONSE",
"message":{
"text":"Hello, world!"
}
}' "https://graph.facebook.com/v20.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..." }
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.
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/v20.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.
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.
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 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 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.
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.
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.
Learn about the components you can add to messages in your conversations.
Learn more about sending messages using the Messenger Platform.