Targeting Broadcast Messages

On October 29, 2019 we announced a breaking change. That all broadcast API will stop working on Jan 15, 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.

By default, the Broadcast API sends your message to all open conversations with your Messenger bot. To allow you broadcast to a subset of conversations, the Broadcast API supports 'custom labels', which can be associated with individual PSIDs.

Contents

Managing Labels

Custom Labels API allows apps to create, update and delete labels for a given Page. For details see, Custom Labels

Sending a Message with a Label

On July 29, 2019 we deprecated Broadcast API for V4.0.

Broadcast API allows targeting based on custom labels. To send a broadcast message to the set of PSIDs associated with a label, include the label ID in the custom_label_id property of the request when you send the broadcast message:

curl -X POST -H "Content-Type: application/json" -d '{    
  "message_creative_id": <BROADCAST_MESSAGE_ID>,
  "custom_label_id": <CUSTOM_LABEL_ID>
}' "https://graph.facebook.com/v3.3/me/broadcast_messages?access_token=<PAGE_ACCESS_TOKEN>"
  

On success, the Messenger Platform will return a broadcast_id:

{
  "broadcast_id": 827  
}

Label Predicates

On July 29, 2019 we deprecated Broadcast API for V4.0. Label Predicates are currently only supported by Broadcast API and not the Send API.

The Broadcast API supports the ability to conditionally apply multiple labels to a broadcast send. This allows you to create intersections and unions between multiple labels to define custom sets of users.

To create a label predicate, set the definition of the predicate in the targeting.labels property of the POST request body when you send your broadcast:

curl -X POST -H "Content-Type: application/json" -d '{
  "message_creative_id": <MESSAGE_CREATIVE_ID>,
  "targeting": {
    "labels": {
      "operator": "<OR|NOT|AND>",
      "values": [
        {
          "operator": "<OR|NOT|AND>",
          "values": [
            <CUSTOM_LABEL_ID>, 
            <CUSTOM_LABEL_ID>, 
            ...
          ]
        },
        {
          "operator": "<OR|NOT|AND>",
          "values": [
            <CUSTOM_LABEL_ID>,
            <CUSTOM_LABEL_ID>,
            ...
          ]
        },
        ...
      ]
    }
  }
}' "https://graph.facebook.com/v3.3/me/broadcast_messages?access_token=xxx"

Supported Operators

Label predicates support the following SQL-like operators:

Operator Description

AND

Performs an intersection of the specified labels. Produces a set of users that are present across all labels.

OR

Performs a union of the specified labels. Produces a set of users that are present in at least one label.

NOT

Performs an except of the specified labels. Produces a set that does not include the users from the specified label.


The NOT operator supports only one value in the values array.

Example Predicate

To understand how label predicates work, let's look at a simple example. Suppose you are an online retailed that has labels for the following user groups:

  • Customers in California
  • Customers below the age of 25
  • Customers above the age of 50

For an upcoming campaign, you want to broadcast a coupon to all users that are either below the age of 25 or above the age of 50.

The label predicate for this broadcast send would look like this:

"targeting": {
  "labels": {
    "operator": "OR", // union all PSIDs that meet desired age
    "values": [
      <UNDER_25_CUSTOMERS_LABEL_ID>, 
      <OVER_50_CUSTOMERS_LABEL_ID>   
    ]    
  }
}

Example Nested Predicate

We can also create more complex label predicates by nesting predicates. For example, let adjust the above predicate to target users that are:

  • Either California-based customers below the age of 25
  • Or above the age of 50

The label predicate for this broadcast would look like this:

"targeting": {
  "labels": {
    "operator": "OR", // union all PSIDs that meet desired age and location
    "values": [
      <OVER_50_CUSTOMERS_LABEL_ID>,          
      {
        "operator": "AND", // intersect customers in California and under 25
        "values": [
          <CALIFORNIA_CUSTOMERS_LABEL_ID>,
          <UNDER_25_CUSTOMERS_LABEL_ID>
        ]
      }
    ]    
  }
}