Targeting Broadcast Messages

Graph API v2.11 Required

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

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

Creating a Label

To create a label, send a POST request to the /custom_labels endpoint:

curl -X POST -H "Content-Type: application/json" -d '{    
  "name": "<LABEL_NAME>",  
}' "https://graph.facebook.com/v2.11/me/custom_labels?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will return an id property in the request.

{
  "id": 1712444532121303  
}

Associating a Label to a PSID

To associate a label to a specific PSID, send a POST request to the /<CUSTOM_LABEL_ID>/label endpoint, and include the PSID you want to associate with the label in the user property of the request body:

curl -X POST -H "Content-Type: application/json" -d '{    
  "user": <PSID>
}' "https://graph.facebook.com/v2.11/<CUSTOM_LABEL_ID>/label?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will respond with the success message:

{
  "success": true  
}

Sending a Message with a Label

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/v2.11/me/broadcast_messages?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will return a broadcast_id:

{
  "broadcast_id": 827  
}

Removing a Label From a PSID

To remove a label currently associated with a PSID, send a DELETE request to the /<CUSTOM_LABEL_ID>/label endpoint, with the user URL parameter set to the PSID you wish to remove:

curl -X DELETE "https://graph.facebook.com/v2.11/<CUSTOM_LABEL_ID>/label?user=<PSID_TO_REMOVE>access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will return a success message:

{
  "success": true  
}

Retrieving Labels Associated with a PSID

To retrieve the labels currently associated with a PSID, send a GET request to the /<PSID>/custom_labels endpoint:

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

The Messenger Platform will return a data object with an array of the associated labels:

{
  "data": [
    {
      "name": "myLabel",
      "id": "1001200005003"
    },
    {
      "name": "myOtherLabel",
      "id": "1001200005002"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUmx1WTBpMGpJWXprYzVYaVhabW55dVpycko4U2xURGE5ODNtNFZAPal94a1hTUnNVMUtoMVVoTzlzSDktUkMtQkUzWEFLSXlMS3ZALYUw3TURLelZAPOGVR",
      "after": "QVFIUmItNkpTbjVzakxFWGRydzdaVUFNNnNPaUl0SmwzVHN5ZAWZAEQ3lZANDAzTXFIM0NHbHdYSkQ5OG1GaEozdjkzRmxpUFhxTDl4ZAlBibnE4LWt1eGlTa3Bn"
    }
  }
}

Retrieving Label Details

To retrieve a single label, send a GET request to the <CUSTOM_LABEL_ID>/custom_labels endpoint. You may optionally set fields=name in the query string to retrieve the label name along with its IDs:

curl -X GET "https://graph.facebook.com/v2.11/<CUSTOM_LABEL_ID>?fields=name&access_token=<PAGE_ACCESS_TOKEN>"

The Messenger Platform will return a data object with an array of labels:

{"name":"myLabel","id":"1001200005002"}

Retrieving a List of All Labels

To retrieve the list of all the labels for the page, send a GET request to the /custom_labels endpoint. You may optionally set fields=name in the query string to retrieve the label names along with their IDs:

curl -X GET "https://graph.facebook.com/v2.11/me/custom_labels?fields=name&access_token=<PAGE_ACCESS_TOKEN>"

The Messenger Platform will return a data object with an array of labels:

{
  "data": [
    {
      "name": "myLabel",
      "id": "1001200005003"
    },
    {
      "name": "myOtherLabel",
      "id": "1001200005002"
    }
  ],
  "paging": {
    "cursors": {
      "before": "QVFIUmx1WTBpMGpJWXprYzVYaVhabW55dVpycko4U2xURGE5ODNtNFZAPal94a1hTUnNVMUtoMVVoTzlzSDktUkMtQkUzWEFLSXlMS3ZALYUw3TURLelZAPOGVR",
      "after": "QVFIUmItNkpTbjVzakxFWGRydzdaVUFNNnNPaUl0SmwzVHN5ZAWZAEQ3lZANDAzTXFIM0NHbHdYSkQ5OG1GaEozdjkzRmxpUFhxTDl4ZAlBibnE4LWt1eGlTa3Bn"
    }
  }
}

Deleting a Label

To delete a label, send a DELETE request to the /<CUSTOM_LABEL_ID> endpoint:

curl -X DELETE -H "Content-Type: application/json" "https://graph.facebook.com/v2.11/<CUSTOM_LABEL_ID>?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Messenger Platform will return a success message:

{
  "success": true  
}

Label Predicates

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/v2.11/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>
        ]
      }
    ]    
  }
}