Grow your Audience for Marketing Message API for Messenger

This guide discusses how a business using your app can increase their number of subscribers. A subscription token represents a person who has subscribed, opted in to receiving marketing messages from a business' Facebook Page. We show you how to increase a business' number of subscribers using the following options:

• Custom Audience API
• Click to Messenger ads
• Opt-in Requests
• Organic Automations

Growing your Audience Options

Option 1: Custom Audience API

For businesses that have a list of customer data such as phone numbers and emails, you can upload this data to match to Facebook users and have subscription tokens be created.

Step 1: Create a Messenger Marketing Messages Custom Audience

Send a POST request tto the act_<AD_ACCOUNT_ID>/customaudiences endpoint with the following required parameters:

• customer_file_source – set to USER_PROVIDED_ONLY
• description – set to the description of the custom audience
• marketing_message_channels – set to an object with MESSENGER set to the business' Facebook Page ID
• name – set to the name of the custom audience
• subscription_info – set to an array with "MESSENGER" as the only item
• subtype – set to CUSTOM
• use_for_products – set to an array with "MARKETING_MESSAGES" as the only item

Sample Request

Formatted for readability.

curl -X POST "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences" \
     -H "Authorization: Bearer <SYSTEM_USER_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "subtype": "CUSTOM",
           "customer_file_source": "USER_PROVIDED_ONLY",
           "name": "<CUSTOM_AUDIENCE_NAME>",
           "description": "<CUSTOM_AUDIENCE_DESCRIPTION>",
           "use_for_products": ["MARKETING_MESSAGES"],
           "subscription_info": ["MESSENGER"],
           "marketing_message_channels": {
             "MESSENGER":  "<PAGE_ID>"
           }
        }'

On success, your app receives a JSON object with a custom audience ID.

{
  "data": [
    {
      "id": "<CUSTOM_AUDIENCE_ID>"
    }
  ]
}

Step 2: Upload users to Custom Audience

After creating a custom audience, you can upload custom information to match with Facebook users. Every user that is matched in the upload will be given a subscription token. You can add an unlimited number of records to an audience, but only up to 10000 at a time. Changes to your Custom Audiences don't happen immediately and usually take up to 24 hours. Match rates typically range from 20% to 70% depending on multiple factors such as the quality of the list and type of identifiers provided.

Send a POST request to the /<CUSTOM_AUDIENCE_ID>/users endpoint with the following required parameters:

Parameters

Input: (+84) 091-2345678 
Output: 84912345678

{ 
  "schema": [
      "EMAIL",
      "PHONE",
      "FN",
      "LN",
    ]
  "data":
    [
      [
        "<HASHED_EMAIL>", 
        "<HASHED_PHONE>", 
        "<HASHED_FIRST_NAME>", 
        "<HASHED_LAST_NAME>"
      ], 
      [
        "<HASHED_EMAIL>", 
        "<HASHED_PHONE>", 
        "<HASHED_FIRST_NAME>", 
        "<HASHED_LAST_NAME>"
      ], 
      [
        "<HASHED_EMAIL>", 
        "<HASHED_PHONE>", 
        "<HASHED_FIRST_NAME>", 
        "<HASHED_LAST_NAME>"
      ], 
    ]
}

Sample Request

curl -X POST "https://graph.facebook.com/<API_VERSION>/<CUSTOM_AUDIENCE_ID>/users" \
     -H "Authorization: Bearer <SYSTEM_USER_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "payload": { 
              "schema":[
                "EMAIL",
                "PHONE",
                "FN",
                "LN",
              ]
              "data":
              [
                [
                  "<HASHED_EMAIL>", 
                  "<HASHED_PHONE>", 
                  "<HASHED_FIRST_NAME>", 
                  "<HASHED_LAST_NAME>"
                ], 
                [
                  "<HASHED_EMAIL>", 
                  "<HASHED_PHONE>", 
                  "<HASHED_FIRST_NAME>", 
                  "<HASHED_LAST_NAME>"
                ], 
                [
                  "<HASHED_EMAIL>", 
                  "<HASHED_PHONE>", 
                  "<HASHED_FIRST_NAME>", 
                  "<HASHED_LAST_NAME>"
                ], 
              ]
            }
        }'

On success, your app receives a JSON object with the number of valid and invalid entries. A job will run asyncronously to match the customer infromation to Facebook users and create the subscription tokens.

{
  "audience_id": "<CUSTOM_AUDIENCE_ID>",
  "num_received": 3,
  "num_invalid_entries": 0,
  "invalid_entry_samples": {
  }
}

Step 3: Webhook Notification for Uploaded Customer Rows Matching Process

Each time a batch of uploaded customer rows matching process completes, a notification is sent to apps subscribed to the marketing_messages_subscriber_upload_status event for that page. To receive these notifications through a webhook, follow the setup instructions in the Meta Webhooks for Messenger Platform.

Sample Payload

{
   "field": "marketing_messages_subscriber_upload_status",
   "app_id": 12313123123123,
   "page_id": 134141414124123,
   "custom_audience_id": 140984918491243,
   "ad_account_id": 12348141984909088,
   "timestamp": 41412414141,
   "num_rows": 1000,
   "business_id": 12313123123123,
   "approximate_count_lower_bound": 105,
   "approximate_count_upper_bound": 120,
   "batch_uploading_status": "SUCCESS"
}

Field Reference

Step 4: Retrieve existing Custom Audiences

In order to get a list of Messenger marketing message custom audiences, you can add the following fields and filter to the /act_<AD_ACCOUNT_ID>/customaudiences endpoint.

Fields:

fields=id,name,messenger_marketing_messages_page

Filters:

filtering=[{"field":"data_source.subtype","operator":"IN","value":[1010]}]

Filters (URL Encoded version):

filtering=%5B%7B%22field%22%3A%22data_source.subtype%22%2C%22operator%22%3A%22IN%22%2C%22value%22%3A%5B1010%5D%7D%5D

Sample Request

curl -X GET "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences?fields=id,name,messenger_marketing_messages_page&filtering=%5B%7B%22field%22%3A%22data_source.subtype%22%2C%22operator%22%3A%22IN%22%2C%22value%22%3A%5B1010%5D%7D%5D" \
     -H "Authorization: Bearer <SYSTEM_USER_ACCESS_TOKEN>" \
     -H "Content-Type: application/json"

Option 2: Click to Messenger ads

Customers or potential customers who click and respond to Click to Messenger ads are automatically subscribed to receive marketing messages; no additional opt-in flow is needed.

Businesses that have onboarded to your app automatically get this functionality for all Click to Messenger ad campaigns.

Visit our Marketing API documentation to learn more about Ads that Click to Messenger.

Option 3: Opt-in Requests

A customer, or potential customer, must first send a message via Messenger to the business' Facebook Page. This event triggers a webhook notification that is sent to your server. This webhook notification contains a Page-scoped ID (PSID) that represents the customer. Your app then uses this PSID to send the customer an opt-in request from the business' Facebook Page.

Visit our Messenger Platform documentation to learn ways to send opt-in requests.

Step 1: Send an opt-in request on Messenger

The following is an example of an opt-in request.

Send a POST request to the /<PAGE_ID>/messages endpoint, where <PAGE_ID> is the ID for the business’s Facebook Page, and include the following properties:

• recipient – an object with id set to the customer's PSID
• page – set to the business' Facebook Page ID
• message.attachment – an object with the following parameters:
  • type – set to template
  • payload – an object set to the message content and any additional information to be sent in the webhooks information
    • template_type – set to notification_messages
    • notification_messages_timezone – set to the customer's time zone
    • title – set to the message title
    • image_url – set to the url for the image in the message
    • payload – set to any addition webhook information

curl -X POST "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/messages" \
     -H "Authorization: Bearer <PAGE_ACCESS_TOKEN>" \
     -Header "Content-Type: application/json" \
     -d '{
           "recipient": { "id": "<PSID>" },
           "page": "<PAGE_ID>",
           "message": {
             "attachment": {
               "type": "template",
               "payload": {
                 "template_type": "notification_messages",
                 "notification_messages_timezone": "<CUSTOMERS_TIME_ZONE>",
                 "title": "<MESSAGE_TITLE>",
                 "image_url": "<IMAGE_URL>",
                 "payload": "<ADDITIONAL_WEBHOOK_INFORMATION>"
               }
             }
           }
        }' 

On success, your app receives a JSON response with the recipient's PSID and message ID.

{ 
   "recipient": {
       "id":"<PSID>",
       "message_id":"<MESSAGE_ID>",
   }
}
  
  

Visit the Messenger Plaform documentation to learn more about available message attachment properties.

Step 2: Handle successful opt-in

When a customer opts in, the messaging_optin webhook event is triggered and a notification is sent to your webhooks server. This webhook contains the subscription token ID your app uses to send marketing messages.

Webhook Notification Payload

{
  "sender": {
    "id": "<PSID>",
  },
  "recipient": {
    "id": "<PAGE-ID>",
  },
  "timestamp": "<TIMESTAMP>}",
  "optin": {
    "type": "notification_messages", 
      "payload": "<ADDITIONAL-WEBHOOK-INFORMATION>",
      "notification_messages_token": "<SUBSCRIPTION_TOKEN_ID>",   // Subscription token
      "notification_messages_timezone": "<TIMEZONE-ID>",
      "user_token_status": "<TOKEN-STATUS>"  
      "notification_messages_status": "<MESSAGE-STATUS>", 
      "title": "<TITLE-FOR-THE-NOTIFICATION>"
    }
}

Option 4: Organic Automations

Enabling organic automations during the business onboarding flow helps boost user engagement and streamline communication. Currently, two automation types are available:

1. High-Intent Comments:
   When a user comments on a business’s public Facebook post with one of six key intents—Purchase, Price, Payment, Product Inquiry, or Appointment Booking—they’re automatically prompted to sign up for updates and promotions through Messenger.

2. Stale Thread Follow-Up (No Reply in 48 Hours):
   If a Messenger conversation between a business’s Facebook Page and a user goes inactive (no replies for 48 hours), the user will receive a prompt inviting them to sign up for updates and promotions via Messenger.

These automations make it easy for businesses to re-engage interested users and nurture leads, creating more opportunities for meaningful connections.

Enable the organic automations during the onboarding experience

Best practices

Use the text to explain how to grow marketing messages audience in your app.

Next steps

Now that you have subscription tokens, start sending marketing messages.