Message Tags

Update: Starting July 30, we will restore the standard Human Agent Tag 7-day response window.

To help businesses manage the larger than expected increase in messaging volume due to the COVID-19 crisis, we had temporarily extended the human agent tag response window from 7 days to 21 days back in April. The extension was valid until July 15, 2020. Starting July 30th, 2020 the response time window for the human agent tag will be restored to 7 days.

To help businesses manage the larger than expected increase in messaging volume due to the COVID-19 crisis, we are temporarily extending the human agent tag response window from 7 days to 21 days. This will give more time for businesses to respond to customers whose inquiries couldn’t be handled in a timely manner. The extension is valid until July 15, 2020. Post July 15, we will re-evaluate if further extension is necessary.

Message tags enable sending important and personally relevant 1:1 updates to users outside the standard messaging window.

Businesses are encouraged to respond within 24 hours to user’s messages and Message tags enable sending important and personally relevant 1:1 updates to users outside the standard messaging window. Businesses may send promotional content using standard messaging and sponsored messages.

Message tags may not be used to send promotional content, including but not limited to deals, offers, coupons, and discounts. Use of tags outside of the approved use cases below may result in restrictions on the Page's ability to send messages. See the Messenger Platform policy for details.

Businesses who want to send a promotional message to many people, outside the standard messaging window, should use sponsored messages. Sponsored messages allows businesses to send targeted messages to re-engage people who currently have an open chat with the business. Learn more in the Sponsored Message documentation. For use cases like back in stock alerts, flash sales, price drop alerts, etc., we recommend using the One-Time Notification API. Learn more in the One-time notification documentation.

Contents

Supported Tags

Tag Description Allowed Disallowed (non-exhaustive)

CONFIRMED_EVENT_UPDATE

Send the user reminders or updates for an event they have registered for (e.g., RSVP'ed, purchased tickets). This tag may be used for upcoming events and events in progress.

  • Reminder of upcoming classes, appointments, or events that the user has scheduled
  • Confirmation of user's reservation or attendance to an accepted event or appointment
  • Notification of user's transportation or trip scheduled, such as arrival, cancellation, baggage delay, or other status changes
  • Promotional content, including but not limited to deals, offers, coupons, and discounts
  • Content related to an event the user has not signed up for (e.g., reminders to purchase event tickets, cross-sell of other events, tour schedules, etc)
  • Messages related to past events
  • Prompts to any survey, poll, or reviews unrelated to a preceding interaction in Messenger

POST_PURCHASE_UPDATE

Notify the user of an update on a recent purchase.

  • Confirmation of transaction, such as invoices or receipts
  • Notifications of shipment status, such as product in-transit, shipped, delivered, or delayed
  • Changes related to an order that the user placed, such credit card has declined, backorder items, or other order updates that require user action
  • Promotional content, including but not limited to deals, promotions, coupons, and discounts
  • Messages that cross-sell or upsell products or services
  • Prompts to any survey, poll, or reviews unrelated to a preceding interaction in Messenger

ACCOUNT_UPDATE

Notify the user of a non-recurring change to their application or account.

  • A change in application status (e.g., credit card, job)
  • Notification of suspicious activity, such as fraud alerts
  • Promotional content, including but not limited to deals, promotions, coupons, and discounts
  • Recurring content (e.g., statement is ready, bill is due, new job listings)
  • Prompts to any survey, poll, or reviews unrelated to a preceding interaction in Messenger

HUMAN_AGENT

(Closed BETA)

Apply for access

Allows human agents to respond to user inquiries. Messages can be sent within 7 days after a user message.

  • Human agent support for issues that cannot be resolved within the standard messaging window (e.g., business is closed for the weekend, issue requires >24 hours to resolve)
  • Automated messages
  • Content unrelated to user inquiry

Sending Messages with Tags

To send a tagged message with the Send API, send a message as you normally would, with the tag property appended to the body of your POST request:

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": { 
    "id": "<PSID>"
  },
  "message":{
    ...
  },
  "messaging_type": "MESSAGE_TAG",
  "tag": "ACCOUNT_UPDATE"
      
}' "https://graph.facebook.com/v9.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"  
    

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

Retrieving Tags (Available until May 4th, 2020)

On February 4th, 2020, we announced the deprecation of this API for retrieving tags. It is no longer supported on versions 6.0 and above of Graph API. On older versions, it will be available till May 4th, 2020. As we have simplified and reduced the number of our message tags, it is recommended to hard code them in your app.

In some cases you may want to provide a list of tags to your customers to choose from. To retrieve the current list of supported tags, send a GET request to the /page_message_tags endpoint of the Graph API:

 
curl -X GET "https://graph.facebook.com/v9.0/page_message_tags?access_token=<PAGE_ACCESS_TOKEN>"
    

The API will return a response in the following format:

{
  "data": [
    {
      "tag": "POST_PURCHASE_UPDATE",
      "description": "Notify the message recipient of an update on an existing transaction."
    }, {
      "tag": "ACCOUNT_UPDATE",
      "description": "Notify the message recipient of a change to their account settings."
    }, 
      
    ...
      
  ]
}