Message Tags

On August 29th, 2019 we announced updates to Message Tags on the Messenger Platform. The newly introduced tags are now available subject to the conditions below. Usage of the current message tags will be supported until January 15, 2020.

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.

Contents

Supported Tags

Suggest a New Message Tag


Don't see a tag that supports your 1:1 messaging use case? Propose a new one, and we will review it for possible inclusion in a future release!

Suggest a Tag →
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

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

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

HUMAN_AGENT

(Closed BETA)

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

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/v5.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."
    }, 
      
    ...
      
  ]
}
    

Current Supported Tags (Available until January 15, 2020)

The following tags, referred as the 'current' tags, are valid until January 15, 2020. The name current simply signals the tags that we are sunseting as part of the August 29th, 2019 announcement. We encourage all apps and Pages to migrate to the new tags to avoid any service disruption.

Tag Allowed Use Cases Examples Migration notes

BUSINESS_PRODUCTIVITY

Send non-promotional messages to help people manage the productivity of their businesses or related activities.

  • Notifications on services or products that a business has subscribed to or purchased from a service provider
  • Reminders or alerts on upcoming invoices or service maintenance
  • Reports on performance, metrics, or recommended actions for the business

Partially covered as a the new tag POST_PURCHASE_UPDATE

COMMUNITY_ALERT

Notify the message recipient of emergency or utility alerts, or issue a safety check in your community.

  • Request a safety check
  • Notify of an emergency or utility alerts

Partially covered as a the new tag NON_PROMOTIONAL_SUBSCRIPTION

CONFIRMED_EVENT_REMINDER

Send the message recipient reminders of a scheduled event which a person is going to attend.

  • Upcoming classes or events that a person has signed up for
  • Confirmation of attendance to an accepted event or appointment

Partially covered as a the new tag CONFIRMED_EVENT_UPDATE

NON_PROMOTIONAL_SUBSCRIPTION

Send non-promotional messages under the News, Productivity, and Personal Trackers categories described in the Messenger Platform's subscription messaging policy. You can apply for access to use this tag under the Page Settings > Messenger Platform.

See Platform Policy Overview - Subscription Messaging

After January 15, 2020 will only be available to Pages on the Facebook News Page Index (NPI),

PAIRING_UPDATE

Notify the message recipient that a pairing has been identified based on a prior request.

  • Match identified in dating app
  • Parking spot available

No longer supported after January 15, 2020

APPLICATION_UPDATE

Notify the message recipient of an update on the status of their application.

  • Application is being reviewed
  • Application has been approved
  • Job application status

Partially covered as the tag ACCOUNT_UPDATE

ACCOUNT_UPDATE

Notify the message recipient of a change to their account settings.

  • Profile has changed
  • Preferences are updated
  • Settings have changed
  • Membership has expired
  • Password has changed

Has a new expanded definition

PAYMENT_UPDATE

Notify the message recipient of a payment update for an existing transaction.

  • Send a receipt
  • Send an out-of-stock notification
  • Notify an auction has ended
  • Status on a payment transaction has changed

Partially covered as the new tag POST_PURCHASE_UPDATE

PERSONAL_FINANCE_UPDATE

Confirm a message recipient's financial activity.

  • Bill-pay reminders
  • Scheduled payment reminder
  • Payment receipt notification
  • Funds transfer confirmation or update
  • Other transactional activities in financial services

Partially covered as the new tag ACCOUNT_UPDATE

SHIPPING_UPDATE

Notify the message recipient of a change in shipping status for a product that has already been purchased.

  • Product is shipped
  • Status changes to in-transit
  • Product is delivered
  • Shipment is delayed

Partially covered as the new tag POST_PURCHASE_UPDATE

RESERVATION_UPDATE

Notify the message recipient of updates to an existing reservation.

  • Itinerary changes
  • Location changes
  • Cancellation is confirmed
  • Hotel booking is cancelled
  • Car rental pick-up time changes
  • Room upgrade is confirmed

Partially covered as the new tag POST_PURCHASE_UPDATE

ISSUE_RESOLUTION

Notify the message recipient of an update to a customer service issue that was initiated in a Messenger conversation.

  • Issue is resolved
  • Issue status is updated
  • Issue requires a request for additional information
  • Follow up on a customer inquiry or support ticket

Partially covered as the new tag HUMAN_AGENT

APPOINTMENT_UPDATE

Notify the message recipient of a change to an existing appointment.

  • Appointment time changes
  • Appointment location changes
  • Appointment is cancelled

Partially covered as the new tag CONFIRMED_EVENT_UPDATE

GAME_EVENT

Notify the message recipient of a change in in-game user progression, global events, or a live sporting event.

  • Player's in-game crops are ready to be collected
  • Player's daily tournament is about to start
  • Person's favorite soccer team is about to begin a match

No longer supported after January 15, 2020

TRANSPORTATION_UPDATE

Notify the message recipient of updates to an existing transportation reservation.

  • Flight status changes
  • Ride is canceled
  • Trip is started
  • Ferry has arrived

Partially covered as the new tag CONFIRMED_EVENT_UPDATE

FEATURE_FUNCTIONALITY_UPDATE

Notify the message recipient of new features or functionality that become available in your bot.

  • Chat with a live agent is added to your bot
  • A new skill is added to your bot

Partially covered as the new tag HUMAN_AGENT

TICKET_UPDATE

Send the message recipient updates or reminders for an event for which a person already has a ticket.

  • Concert start time changes
  • Event location changes
  • Show is cancelled
  • A refund opportunity is made available

Partially covered as the new tag CONFIRMED_EVENT_UPDATE