Broadcasting Messages to Multiple Conversations

On October 29, 2019 we announced a breaking change. That all broadcast API will stop working on March 4th, 2020. Matching the deprecation date set by the policy update shared on August 29, 2019.

We recommend apps to migrate to the new policy and migrate to use the Send API as soon as possible.

Breaking Change Notice - Page-level Subscription Messaging Feature Requirement

Starting April 30, 2019, a Page must be approved with the Page-level Subscription Messaging feature in order to use the Broadcast API. Apps were granted the subscription messaging permission at the app-level will no longer be respected. This change is in effect immediately to v3.3+ of the Graph API, and will apply to all lower versions on July 31, 2019.

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 been approved for subscription messaging 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.



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

  • pages_messaging
  • subscription messaging

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


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 the 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 '{    

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 reference the previously created message_creative_id in 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": "SILENT_PUSH",
  "messaging_type": "MESSAGE_TAG",

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 "<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"

Scheduling Broadcasts

The Broadcast API supports advanced scheduling of broadcast sends. To schedule a broadcast, specify the schedule_time property when you make the API request to send the message. ISO-8601 and Unix timestamp formats are accepted. For example 2018-04-05T20:39:13+00:00 and 1522960753 both represent 8:39:13pm 04/05/2018 (UTC)

curl -X POST -H "Content-Type: application/json" -d '{    
  "message_creative_id": <MESSAGE_CREATIVE_ID>,
  "schedule_time": "<ISO-8601_OR_UNIX_TIMESTAMP>"

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>

Cancelling a Scheduled Broadcast

To cancel a scheduled broadcast, send a POST request to the /<BROADCAST_ID> endpoint, with "operation": "cancel" in the request body:

curl -X POST -H "Content-Type: application/json" -d '{
  "operation": "cancel"
}' "<BROADCAST_ID>?access_token=<PAGE_ACCESS_TOKEN>"

On success, the API will respond with a success message:

{ "success": true }

Finding a Broadcast ID

Get a list of broadcast_id's by sending a GET request to the broadcast_messages node

  curl -i -X GET \

Fields include limit, scheduled_time, status, and insight.

  "scheduled_time": "<ISO-8601_FORMAT_TIME>",

Checking Broadcast Status

Once you have scheduled a broadcast send, you can check on its status by sending a GET request to the /<BROADCAST_ID> endpoint with the fields URL param:

curl -X GET "<BROADCAST_ID>?fields=scheduled_time,status&access_token=<PAGE_ACCESS_TOKEN>"

The API will respond with the time the broadcast is scheduled for, and one of the following statuses:

  • SCHEDULED: Broadcast is scheduled but has not been sent.
  • IN_PROGRESS: Broadcast has been initiated and is still in-progress.
  • FINISHED: Broadcast was completed successfully.
  • CANCELED: Broadcast was canceled by the developer.
  "scheduled_time": "<ISO-8601_FORMAT_TIME>",

Broadcast API Limits

The Broadcast API's is limited in reach and call rate. For more information, see: