Create and send messages to your customers or people interested in your Facebook Page.
Before You Start
You will need:
- A Page access token requested by a person who can perform the
MESSAGE task on the Page
- The message recipient must have sent your Page a message within the last 24 hours or agreed to receive messages from your Page outside of the standard 24 hour messaging window
- Message tags can not be used to send promotional content
To send a message to a person, send a
POST request to the
/PAGE-ID/messsages endpoint with the
recipient parameters set, and the message content.
Formatted for readability.
The following example is a response to a person's message where the message your Page is sending is text only.
curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
On success, your app will receive the following JSON response:
The type of message your Page is sending. Either
attachement must be set when using this parameter.
attachment object – Previews the URL. Used to send messages with media or Structured Messages.
attachment must be set.
type – Type of attachement. Can be
video. Maximum file size is 25MB
payload – An object containing a template content or file content
metadata – A string of additional data you want to pass in the
message_echo webhook. Must be less than 1000 characters
quick_replies – An array of quick replies to be sent in a message
text – A message containing text only. Must be UTF-8 and less than 2000 characters.
The type of message being sent
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.
Type of push notification a person will receive
NO_PUSH – No notification
REGULAR (default) – Sound or vibration when a message is received by a person
SILENT_PUSH – On-screen notification only
The person who will receive the message your Page is sending
id – The Page-scoped ID for the person that is used to sen a message in response to a message received by your Page within the last 24 hours or for a person who has agreed to receive messages from your Page outside the standard 24 hour messaging window
user_ref – The reference for the person that is used to send a message in response to a Checkbox or Customer Chat Plugin
comment_id – The ID for the comment that is used to send a message as a Private Reply in response to a visitor Comment on your Page Post
post_id – The ID for the Page Post that is used to send a message as a Private Reply in response to a visitor Post on your Page
The action icon shown in the messaging window representing the action taken by the Page on a message the Page has received from a person.
typing_on – Display the typing bubble when the Page is preparing a response
typing_off – Do not display the typing bubble
mark_seen – Display the seen icon for messages that have been seen by the Page
Can only be sent with the
recipient parameter. Cannot be sent with the
message parameter but must be sent as a separate request.
A tag that enables your Page to send a message to a person outsde the standard 24 hour messaging window.
ACCOUNT_UPDATE – Tags the message you are sending to your customer as a non-recurring update to their application or account. Not available for Instagram Messaging API
CONFIRMED_EVENT_UPDATE – Tags the message you are sending to your customer as a reminder fo an upcoming event or an update for an event in procgres for which the customer is registered. Not available for Instagram Messaging API
CUSTOMER_FEEDBACK – Tags the message you are sending to your customer as a Customer Feedback Survey. Customer feedback messages must be sent within 7 days of the customer's last message. Not available for Instagram Messaging API
HUMAN_AGENT – When this tag is added to a message to a customer, it allows a human agent to respond to a person's message. Messages can be sent within 7 days of the person's. Human agent support is for issues that cannot be resolved within the standard 24 hour messaging window
** Apps should apply for the
Human Agent permission via the Developer App dashboard. Navigate to App dashboard -> App review -> Permissions & Features -> Human Agent. Those apps that were previously approved for beta access to the Human Agent permission do not need to re-apply for access.
Human Agent permission is not available in standard access/dev mode. You will need to complete the app review process before you can leverage the human agent tag. During app review submission, please provide clear instructions and demo on how you intend to leverage the human agent tag in your experiences.
POST_PURCHASE_UPDATE – Tags the message you are sending to your customer as an update for a recent purchase made by the customer