Messenger Platform

 
 
 

Message Tags

Message tags give you the ability to send messages to a person outside of the normally allowed 24-hour window for a limited number of purposes that require continual notification or updates. This enables greater flexibility in how your bot interacts with people, as well as the types of experiences you can build on the Messenger Platform.

Allowed Usage - No Promotional Content

Please note that message tags are for sending non-promotional content only.

Using tags to send promotional content (ex: daily deals, coupons and discounts, or sale announcements) is against Messenger Platform policy.

For complete details on allowed usage of message tags, review the supported tags below, and see the Messenger Platform policy.

Contents

Supported Tags

Each message tag may only be used for the use cases listed under 'Allowed Use Cases' below. Using tags to send promotional content (ex: daily deals, coupons and discounts, or sale announcements) is against policy.

Suggest a New Message Tag


None of the currently supported message tags fit your use case? Propose a new one, and we will review it for possible inclusion in a future release!

Suggest a Tag →
Tag Allowed Use Cases Examples

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

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

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

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

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

ISSUE_RESOLUTION

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

  • Issue is resolved
  • Issue status is updated
  • Issue requires a request for additional information

APPOINTMENT_UPDATE

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

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

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

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

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

TICKET_UPDATE

Notify the message recipient of updates pertaining to 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

Sending Messages with Tags

Supported Message Types

Only generic template messages can be sent with tags other than ISSUE_RESOLUTION. ISSUE_RESOLUTION tag can be used with either generic template messages or text messages.

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":{
    ...
  },
  "tag": "SHIPPING_UPDATE"
}' "https://graph.facebook.com/v2.6/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/v2.6/page_message_tags?access_token=<PAGE_ACCESS_TOKEN>"
    

The API will return a response in the following format:

{
  "data": [
    {
      "tag": "SHIPPING_UPDATE",
      "description": "The shipping_update tag may only be used to provide a shipping status notification for a product that has already been purchased. For example, when the product is shipped, in-transit, delivered, or delayed. This tag cannot be used for use cases beyond those listed above or for promotional content (ex: daily deals, coupons and discounts, or sale announcements)."
    }, {
      "tag": "RESERVATION_UPDATE",
      "description": "The reservation_update tag may only be used to confirm updates to an existing reservation. For example, when a hotel booking is canceled, a car rental pick-up time changes, or a room upgrade is confirmed. This tag cannot be used for use cases beyond those listed above or for promotional content (ex: daily deals, coupons and discounts, or sale announcements)."
    }, 
      
    ...
      
  ]
}