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/v5.0/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/v5.0/<CUSTOM_LABEL_ID>/label?access_token=<PAGE_ACCESS_TOKEN>"

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

{
  "success": true  
}

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/v5.0/<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

Currently, Messenger Platform do not support retrieving labels for Messenger accounts that were created using a phone number instead of a Facebook account.

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/v5.0/<PSID>/custom_labels?fields=name&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/v5.0/<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/v5.0/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/v5.0/<CUSTOM_LABEL_ID>?access_token=<PAGE_ACCESS_TOKEN>"
  

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

{
  "success": true  
}

Lead Generation Labels

All incoming messages from the lead generation in Messenger advertising campaigns are classified by four labels: Lead in Progress, Lead Complete, Lead Incomplete, and Lead Disqualified. These labels are meant to help businesses manage their conversations and prioritize the highest intent leads.

Definition of the labels are:

  • Lead in Progress, when the questions are in the process of being answered;
  • Lead Complete, when all of the questions are complete and leads received the Thank You note;
  • Lead Incomplete, when the questions are abandoned 48h after the first message;
  • Lead Disqualified, when the lead replies with a disqualifying answer.

Messages that have completed all of the advertiser’s questions will have a “Lead Complete” label. We recommend filtering messages by this label to show only the most relevant conversations to the Social Care or live agent teams who follow up with leads. You can filter out messages that are not complete (“Lead in Progress“) and creating a rule or condition to exclude from the inbox until they are “Lead Complete”.

You can bring messages back into the inbox when you see the label “Lead Complete”, which means the lead has answered all of the questions and is ready for follow up with an agent.

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>
        ]
      }
    ]    
  }
}