Custom Labels

Custom Labels allows businesses to create labels (e.g., VIP customer) for the customers they communicate with. These labels help businesses to organize and prioritize the customers. These labels can be created by the business either in Facebook Page Inbox or via any customer service platforms that the business might already be using for their business. The Custom Labels API allows developers to sync labels between Facebook Page Inbox and the customer service platforms and vice versa. Using the Custom Labels API, developers provide businesses the ability to create, update and delete labels within their own tools and sync it with Facebook Page Inbox.

Graph API v12.0+ Custom Labels API name field will be replaced with page_label_name. This change will take effect on all older Graph API versions starting Dec 14th, 2021. Developer should leverage page_label_name across various CRUD (Create, Retrieve, Update, Delete) API calls and webhooks.

Accepting Page Contact Terms to use Custom Labels
Webhook
Creating a Label
Associating a Label to a PSID
Removing a Label From a PSID
Retrieving Labels Associated with a PSID
Retrieving Label Details
Retrieving a List of All Labels
Deleting a Label
Lead Generation Labels

Accepting Page Contact Terms to use Custom Labels

In order to use the Custom Labels API after October 1st, 2021 businesses (Page admins) need to accept our new Page Contact Terms. These terms describe Meta’s data practices for the Custom Labels created by the business. We will be rolling out the Page Contact Terms acceptance requirement to Facebook Pages on a rolling basis starting October 1st.

Here’s our recommendation on how you can be better prepared for this upcoming change. It’s vital that you follow the below steps to avoid any business disruption.

Step 1: Developer partners can provide an option within their tools to inform Page admins that they need to accept the Page Contact terms if the business wants to add/edit/delete labels for any of their customers. Our suggestion is to provide an interstitial/dialog within your app and have the page admins/business click on a Call to Action button that redirects the page admin to the Page Contact Terms landing page. Here’s the suggested copy in the interstitial/dialog box.

[Partner to translate as appropriate] Hi Page name, To use labels that sync with your Facebook Page Inbox, you must first accept the Page Contact Terms. You can continue to create, update and delete labels once you've accepted these terms.
Step 2: Call the custom labels endpoint. If the Page hasn’t accepted the terms, the API call will return an error (see details below) with a link to the Page Contact Terms. When the API returns an error, you can surface a pop-up in your tool as suggested in step 1. Note that the Page needs to accept the Page Contact Terms only once when they are using labels via your platform.

Error response if Page hasn’t accepted Page Contact Terms

When the app calls the custom labels end point, they will receive an error (see below) if the Page hasn’t accepted the Page Contact Terms of Service. The developer can process the error and use the text from the “error_user_msg” to display a dialog box within the developer tool. The user can then click on the URL and accept the Page contact terms.

Note that the Page ID in the URL will be automatically populated by Facebook when returning the error. The URL is Page specific and will only be available once the Page Contact Terms acceptance is rolled out to the page starting Oct 1st 2021.

    
  "error": {
    "message": "Service temporarily unavailable",
    "type": "OAuthException",
    "is_transient": false,
    "code": 2,
    "error_subcode": 2018344,
    "error_user_title": "Privacy ToS not accepted",
    "error_user_msg": "To use the inbox label API, you need to accept the privacy ToS. Click the link to accept. https://www.facebook.com/100841475479486/inbox/page_contact_tos/",
    "fbtrace_id": "AskTenGWtnk4YI_39tEfagJ"  
  }

Note that only Page admins of the Facebook Page can accept the Page Contact terms.

Webhook

The following webhook will be delivered when there is an update to the labels on a particular user thread (PSID). In order to receive the webhooks, you will need to subscribe to inbox_labels webhook topic with v12.0 or higher.

 {
   "object":"page",
   "entry":[
      {
         "id": "<PAGE_ID>",
         "time":1588007546,
         "changes":[
            {
               "value":{
                  "user":{
                     "id":"<USER_PSID>"
                  },
                  "action":"remove",
                  "label":{
                     "id": "<LABEL_ID>",
                     "page_label_name":"Important"
                  }
               },
               "field":"inbox_labels"
            }
         ]
      }
   ]
}

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 '{    
  "page_label_name": "<LABEL_NAME>",  
}' "https://graph.facebook.com/v21.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/v21.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/v21.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/v21.0/<PSID>/custom_labels?fields=page_label_name&access_token=<PAGE_ACCESS_TOKEN>"

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

{
  "data": [
    {
      "page_label_name": "myLabel",
      "id": "1001200005003"
    },
    {
      "page_label_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/v21.0/<CUSTOM_LABEL_ID>?fields=page_label_name&access_token=<PAGE_ACCESS_TOKEN>"

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

{"page_label_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=page_label_name in the query string to retrieve the label names along with their IDs:

curl -X GET "https://graph.facebook.com/v21.0/me/custom_labels?fields=page_label_name&access_token=<PAGE_ACCESS_TOKEN>"

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

{
  "data": [
    {
      "page_label_name": "myLabel",
      "id": "1001200005003"
    },
    {
      "page_label_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/v21.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.