Messenger Platform

Broadcast API Reference

Breaking Change Notice - Page-level Subscription Messaging Permission

As of the release of Messenger Platform v2.3, permission to send subscription messages will be granted at the Page-level rather than at the app-level.

As we continue to review our Subscription Messaging policies, developers provided access to send messages via app-level permissions may continue to do so until further notice. We highly encourage developers to migrate to the Page-level permission as soon as possible as we evaluate potential updates to this policy.

For more information on handling this transition, see Messaging Transitioning from App-level to Page-level Subscription Messaging

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

The broadcast message is displayed on the Page inbox only when a user replies in a thread.

For more information on using the Broadcast API, see Broadcasting Messages to Multiple Conversations.

Contents

Request URI

Create Message Creative

https://graph.facebook.com/v3.2/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>

Send Broadcast

https://graph.facebook.com/v3.2/me/broadcast_messages?access_token=<PAGE_ACCESS_TOKEN>

Example Request

Create Message Creative

curl -X POST -H "Content-Type: application/json" -d '{    
  "messages": [
    {
      "attachment":{
        "type":"template",
        "payload":{
          "template_type":"generic",
          "elements":[
             {
              "title":"Welcome to Our Marketplace!",
              "image_url":"https://www.facebook.com/jaspers.png",
              "subtitle":"Fresh fruits and vegetables. Yum.",
              "buttons":[
                {
                  "type":"web_url",
                  "url":"https://www.jaspersmarket.com",
                  "title":"View Website"
                }              
              ]      
            }
          ]
        }       
      }
    }
  ]
}' "https://graph.facebook.com/v3.2/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>"

Send Broadcast

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

Properties

Create Message Creative

Property Type Description

messages

Array

The messages to send.


For information on supported message types, see Broadcasting Messages.

Send Broadcast

Property Type Description

message_creative_id

Integer

The message_creative_id of the message creative to send in the broadcast. Each message creative can only be sent once.

notification_type

String

Optional. Push notification type:

  • REGULAR: sound/vibration
  • SILENT_PUSH: on-screen notification only
  • NO_PUSH: no notification

Defaults to REGULAR.

messaging_type

String

Must be set to MESSAGE_TAG

tag

String

Must be set to NON_PROMOTIONAL_SUBSCRIPTION

Response

Create Message Creative

{
  "message_creative_id": 938461089,
}
Property Type Description

message_creative_id

Integer

The unique ID of the message creative.

Send Sponsored Message

{
  "broadcast_id": 827  
}
Property Type Description

broadcast_id

Integer

The unique ID of the sent broadcast.

Audience Limits

Broadcast API reach is limited to 10,000 recipients per message. Depending on the audience size messages might not be sent all at once. This limit does not apply to pages on high-MPS Mode.

To avoid hitting this limit the suggestion is to target smaller audiences by using Targeting Broadcast Messages.

Call Rate Limits

Calls to the broadcast API are rate limited to 10 calls per 60 seconds per page; calls that exceed this rate will fail with error code 613.