Broadcasting Messages to Multiple Conversations

Graph API v2.11 Required

This API is available only in Graph API v2.11 and above.

While the most common way to interact with people on Messenger is for your bot to engage in one-on-one conversations, it is sometimes necessary to send a message to many recipients. For example, Messenger bots that have the pages_messaging_subscriptions permission often need to send updates to tens of thousands of subscribers or more.

Sending a message to many recipients can be inefficient to accomplish with the Send API, as each recipient requires a separate API request. For Messenger bots that need to send to a very high number of recipients, this means sending messages in batches to avoid hitting the Messenger Platform's rate limit, which can take a very long time.

The Messenger Platform's Broadcast API is built on a new infrastructure that allows you to broadcast to everyone that currently has an open conversation with your Page or a custom set of people.

Contents

Requirements

To use the broadcast API, your Messenger bot must have the following permissions:

  • pages_messaging
  • pages_messaging_subscriptions

Please note, messages sent using the Broadcast API must be non-promotional and adhere to the Messenger Platform's subscription messaging policy.

Visibility

Broadcast messages are only visible to the message recipient. Broadcast messages will not appear in the Page inbox.

If your Facebook app is in development mode, broadcast messages will only be sent to users that have been granted the Admin, Developer, or Tester roles for your app.

Creating a Broadcast Message

Unlike the Send API, which allows you to define your message at the time it is sent, messages sent with the Broadcast API must be defined in advance.

To create a broadcast message, send a POST request to the /message_creatives endpoint, where <MESSAGE_OBJECT> is any message you would normally send via the Send API. Only one message may be defined per Message Creative.

For complete details on request properties, see Broadcast API Reference.

curl -X POST -H "Content-Type: application/json" -d '{    
  "messages":[
    <MESSAGE_OBJECT>
  ]
}' "https://graph.facebook.com/v2.11/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>>"

On success, the Broadcast API will return an object with a message_creative_id property that can be used to send the message:

{
  "message_creative_id": <BROADCAST_MESSAGE_ID>,
}

Unsupported Message Templates

The following message templates are not supported:

  • Airline boarding pass template
  • Airline check-in template
  • Airline itinerary template
  • Airline flight update template
  • Receipt template
  • Open graph template

Personalizing Messages

Text Message Support Only

Currently, personalization is only available for broadcasting text messages. The template strings will not work for other message types, such as template messages.

To create a better experience for the message recipient, the Broadcast API supports the following template strings that can be used to include the message recipient's name in broadcast messages:

  • {{first_name}}
  • {{last_name}}

To create a personalized text message, use the dynamic_text object to define your message. To handle the possibility your Messenger bot may not have permission to access a person's name, the dynamic_text.fallback_text property is required. This will be used in place of dynamic_text.text if the person's name cannot be retrieved.

"messages": [
  {
    "dynamic_text": {
      "text": "Hi, {{first_name}}!",
      "fallback_text": "Hello friend!"
    } 
  },
  ...
]

Sending a Broadcast Message

To send a broadcast message, send a POST request to the broadcast_messages endpoint, and include the broadcast message ID in the message_creative_id property of the body of the request.

By default, broadcast messages are sent to all open conversations. For information on targeting broadcast messages, see Targeting a Broadcast Message below.

For complete details on request properties, see Broadcast API Reference.

curl -X POST -H "Content-Type: application/json" -d '{    
  "message_creative_id": <MESSAGE_CREATIVE_ID>,,
  "notification_type": "<REGULAR | SILENT_PUSH | NO_PUSH>",
  "tag": "<MESSAGE_TAG>"
}' "https://graph.facebook.com/v2.11/me/broadcast_messages?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will return a numeric broadcast_id that can be used to identify the broadcast for analytics purposes:

{
  "broadcast_id": <BROADCAST_ID>
}

Webhook Events

Delivery receipts, read receipts and echo webhook events will not be returned for broadcast messages.

Targeting a Broadcast Message

By default, the Broadcast API sends your message to everyone that has an open conversation with your Messenger bot. To ensure your Messenger experience delivers high-quality, relevant content to message recipients, we recommend that you create targeted audiences for your broadcast messages with custom labels.

For more information, see Targeting Broadcasts.

Estimating Broadcast Size

The Broadcast API's reach estimation feature allows you to retrieve an estimate of the approximate number of people that will receive a broadcast message before it is sent.

For more information, see Estimating Broadcast Size.

Broadcast Metrics

Once a broadcast has been delivered, you can find out the total number of people it reached by sending a GET request to the <broadcast_id>/insights/messages_sent endpoint:

curl -X GET "https://graph.facebook.com/v2.11/<broadcast_id>/insights/messages_sent?access_token=<PAGE_ACCESS_TOKEN>"

On success, the API will return a count of the recipients:

{
  "data": [
    {
      "name": "messages_sent",
      "period": "lifetime",
      "values": [
        {
          "value": 1000,
          "end_time": "1970-01-02T00:00:00+0000"
        }
      ],
      "title": "Lifetime number of messages sent from the page broadcast",
      "description": "Lifetime: The total number of messages sent from a Page to people.",
      "id": "1301333349933076/insights/messages_sent"
    }
  ]
}