Meta Marketing API

Messenger Ads

This guide explains how to create and publish a variety of Messenger ads using the Marketing API and Messenger Platform.

Ad Creation Overview

To create and publish an ad you will:

  1. Create an ad campaign
  2. Create an ad set that links your ads to your ad campaign
  3. Create an ad creative for the Messenger Ad type you want to serve
  4. Create an ad by linking your ad creative to your ad set
  5. Publish your ad to Facebook, Instagram, and Messenger

Ad Types

Ads that Click to Messenger

Ads that click to Messenger are Facebook, Instagram or Messenger ads that drop people into a chat with your business. Use these ads to reach people at scale and deliver standout, individualized service.

Ads that click to Messenger support messages with an image, a video, a carousel, or a slideshow. You can also include a call prompt or multiple message templates in your ad.

Ads that Click to Messenger, Lead Generation

Ads that click to Messenger for lead generation give businesses the ability to generate and qualify leads through an automated question and answer flow in Messenger using an automated chat template. This template will create an ad that clicks to Messenger that allows your business to qualify leads and continue the conversation with people interested in your business. Businesses can gather customer preferences and create disqualifying questions to prioritize the most qualified leads.

Ads that Click to Subscribe

Ads that click to subscribe can help you reach new customers who may be interested in receiving marketing messages from you in Messenger. Marketing messages (formerly known as Recurring Notifications) allow you to connect and engage with your customers in an automated and ongoing conversation. When you set up ads with the marketing messages template, people who click on your ad will see an invitation allowing them to opt-in to your marketing messages. Once they opt-in, you can send marketing messages up to once per day that may help boost engagement of your content or drive sales of your product.

Note: If a customer does not opt-in, they will not receive marketing messages.

Sponsored Messages

Sponsored messages let you send offers, promotions and updates directly to the people your business talks to on Messenger. If you have already connected with your customers on Messenger, either through automation for Messenger or live chat support, use sponsored messages to reengage them.

Before You Start

This guide assumes you have:

To make successful calls to all endpoints in this guide, you will need:

  • A Page access token requested by a person who can perform the ADVERTIZE task on the Page
  • The following permissions must be granted a person using your app:
    • ads_management
    • pages_manage_ads
    • pages_read_engagement
    • pages_show_list

Step 1. Create a Campaign

To create your ad campaign send a POST request to the act_ad_account_id/campaigns endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • buying_type
  • name
  • objective – set to OUTCOME_TRAFFIC, or OUTCOME_LEADS for lead ads
  • special_ad_categories
  • status

Ad Campaign Quick Reference

Example Request

Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/campaigns" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"Your_page_access_token",
           "buying_type":"AUCTION",
           "name":"Messenger_ad_campaign_name",
           "objective":"OUTCOME_TRAFFIC",
           "status":"PAUSED",
           "special_ad_categories":["NONE"],
         }'

On success your app receives a JSON response with the ID for your campaign.

{
  "id": "campaign_id"
}

Step 2. Create an Ad Set

To create an ad set, send a POST request to the act_ad_account_id/adsets endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • bid_amount
  • billing_event set to IMPRESSIONS
  • campaign_id
  • daily_budget
  • destination_type set to MESSENGER
  • name
  • optimization_goal set to CONVERSATIONS, IMPRESSIONS, or LEAD_GENERATION or QUALITY_LEAD for lead ads
  • promoted_object – set to the ID for your business' Facebook Page. Required for Sponsored Messages
  • status set to PAUSED
  • targeting – Sponsored messages requires device_platforms to include both mobile and desktop

Ad Set Quick Reference

Example Request

Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/adsets"
     -H "Content-Type: application/json" 
     -d '{
           "access_token":"Your_page_access_token",
           "bid_amount":"Your_bid_amount",
           "billing_event":"IMPRESSIONS",
           "campaign_id":"Your_campaign_id",
           "daily_budget":"Your_daily_budget",
           "destination_type":"MESSENGER",
           "name:"Your_messenger_adset_name",
           "optimization_goal:IMPRESSIONS",
           "status:PAUSED",
           "targeting":{ 
             "geo_locations": { "countries":["US","CA"] },
             "device_platforms": ["mobile", "desktop"],
             "publisher_platforms": ["messenger"] 
           } 
         }'

On success your app receives the following JSON response with the ID for the ad set.

{
  "id": "adset_id"
}

Step 3. Create Ad Creative

The ad creative allows you to add assets to your ads.

Limitations

  • Ads created using object_story_id are not supported
  • A person must have Messenger installed on their device to see your ad
  • There is no support for right side placements

To create an ad creative, send a POST request to the /act_ad_account_id/adcreatives endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • messenger_sponsored_message – Required for Sponsored Messages
  • name
  • object_id – Required for Sponsored Messages
  • object_story_spec – Required
  • object_type – Required for Sponsored Messages
  • privacy_url – Required for lead ads
  • standard_enhancements.enroll_status – Required for ad creatives that are eligible for standard enhancements.

Top Level Ad Creative Parameter Quick Reference

Ads that Click to Messenger

To create an ad creative for a Click to Messenger ad, send a POST request to the /act_ad_account_id/adcreatives endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • name
  • object_story_spec with a *_data object that defines the media type

Image Ad Quick Reference

Image Ad Example Request

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/adcreatives"
     -H "Content-Type: application/json" 
     -d '{
           "access_token":"page_access_token",
           "name":"Your_CTM_image_ad_name",
           "object_story_spec":{
             "page_id": "your_page_id",
             "link_data": { 
               "page_welcome_message": "Your_welcome_message",
               "image_hash": "Your_image_hash", 
               "link": "Your_image_URL", 
               "call_to_action": {
                 "type":"LEARN_MORE",
                 "value":{ "app_destination":"MESSENGER" }
               }   
             }
           }
         }'

Click to Messenger Video Ad Quick Reference

Video Ad Example Request

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/adcreatives"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "page_access_token",
           "name": "Your_CTM_image_ad_name",
           "object_story_spec": {
             "page_id": "your_page_id",
             "video_data": { 
               "call_to_action": {
                 "type": "LEARN_MORE",
                 "value": { "app_destination": "MESSENGER" }
               },
               "link_description": "Your_link_description",
               "image_url": "Your_thumbnail_URL", 
               "page_welcome_message": "Your_welcome_text",
               "video_id": "video_id"
             } 
           }
         }'

Click to Subscribe

Click to Subscribe ads (CTS) are Click to Messenger ads where the object_story_spec.page_welcome_message is an array of objects with a notification message template. When a person clicks the Get messages button in your ad, the person agrees to receive marketing messages from your business.

To create an ad creative for a Click to Subscribe ad, send a POST request to the /act_ad_account_id/adcreatives endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • name
  • object_story_spec with
    • a *_data object that defines the media type
    • the page_welcome_message array that defines the marketing message opt in request. Must include landing_screen_type set to marketing_messages and the message attachment payload.template_type set to nofitication_messages

Image Ad Example Request

Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/adcreatives"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "page_access_token",
           "name": "Your_CTS_image_ad_name",
           "object_story_spec": {
             "page_id": "your_page_id",
             "link_data": { 
               "image_hash": "Your_image_hash", 
               "link": "Your_image_URL", 
               "call_to_action": {
                 "type": "LEARN_MORE",
                 "value":{ "app_destination": "MESSENGER" }
               }
               "page_welcome_message": "{
                 "landing_screen_type": "marketing_messages",
                 "media_type": "image",
                 "image_format": {
                   "customer_action_type": "buttons",
                   "message": {
                     "text": "Your_welcome_message",
                     "attachment": {
                       "type": "template",
                       "payload":{
                         "template_type":"notification_messages",
                         "elements": [{
                             "title": "Your_CTS_title",
                             "subtitle": "Your_CTS_subtitle",
                             "image_url": "Your_image_URL",
                             "app_id": "Your_Meta_app_ID",
                             "buttons": [{
                               "type": "postback",
                               "payload": "Data_to_include_in_webhook_notification",
                               "title": "Get messages"
                             }]
                         }]
                       }
                     }
                   } 
                 }
               }"
             }
           }
         }'

Lead Ads in Conversations

Messenger Ads for Leads allow you to generate leads in Messenger through an automated chat template. You can ask specific questions to people who are interested in your business directly in your preferred messaging platform, gather customer preferences, and ask custom questions to prioritize the most qualified leads.

Before you can create ad creatives for Messenger Ads for Leads you must accept the terms and conditions for Messenger Ads for Leads.

Message Template Requirements

  • A welcome message that greets people after they tap on your ad and let them know what your business has to offer
  • Questions that gather information about whether the person is a lead. This can include questions about interests, location, and contact information such as email and phone number.
  • A confirmation message that allows you to thank people for their answers and let them know what happens next. You can find your new lead in Ads Manager, your Page's publishing tool or in your CRM.
  • A Privacy Policy since you will be collecting customer information.

Limitations

  • Message templates cannot be edited or deleted once they are created

Create a Message Template

To create a message template, send a POST request to the /page_id/messenger_lead_forms endpoint where page_id is the ID for your business' Facebook Page. Your request must include:

  • access_token
  • privacy_url
  • step_list array that includes message, reply_type, step_id, and step_type
  • template_name
  • reminder_text

The following message template includes your template_name, your privacy_url, step_list with a welcome message in step_id: 0, questions in step_id: 1 to 4, a confirmation message in step_id: 5, and a disqualification message in step_id: 6.

Message Template Quick Reference

Example Leads Message Template

Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
curl -X POST "https://graph.facebook.com/v18.0/your_page_ID/messenger_lead_forms"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "privacy_url": "Your_privacy_policy_URL",
           "reminder_text": "Your_reminder_text",
           "template_name": "Your_template_name",
           "step_list": [
             {
               "step_id": "0",
               "message": "Your_welcome_message",
               "step_type": "INTRO",
               "reply_type": "NONE",
               "next_step_ids": "1"
             },
             {
               "step_id": "1"
               "message": "Are_you_interested_in_our_products_or_services?",
               "step_type": "QUESTION",
               "reply_type": "QUICK_REPLIES",
               "answers": ["Yes", "Not now", "Maybe"],
               "next_step_ids": [2,6,2],
               "allow_to_skip": false,
               "answer_validation_enabled": true
             },
             {
               "step_id": "2",
               "message": "What city do you live in?",
               "step_type": "QUESTION",
               "reply_type": "PREFILL",
               "prefill_type": "CITY",
               "next_step_ids": "3",
               "allow_to_skip": true
             },
             {
               "step_id": "3",
               "message": "What is your phone number?",
               "step_type": "QUESTION",
               "reply_type": "PREFILL",
               "prefill_type": "PHONE",
               "next_step_ids": "4",
               "allow_to_skip": false,
               "answer_validation_enabled": true
             },
             {
               "step_id": "4",
               "message": "What is your email address?",
               "step_type": "QUESTION",
               "reply_type": "PREFILL",
               "prefill_type": "EMAIL",
               "next_step_ids": "5",
               "allow_to_skip": false,
               "answer_validation_enabled": true
             },
             {
               "step_id": "5",
               "message": "Your_confirmation_message",
               "step_type": "CONFIRMATION",
               "reply_type": "NONE"
             },
             {
               "step_id": "6",
               "message": "Your_disqualification_message",
               "step_type": "DISQUALIFY",
               "reply_type": "NONE"
             }
           ]
        }'

On success your app will receive a JSON object with the ID for the template.

{
  "id": "your_messenger_lead_gen_template_id"
}

A fblead_form is also created and associated with the message template as part of this process.

Get a list of forms

To get a list of the Messenger lead generation form templates, you can send a GET request to the /page_id/messenger_lead_forms endpoint. You can also get information about a specific template by sending a GET request to /Your_messenger_lead_gen_template_id endpoint.

Ad creative examples

To create an ad creative for lead ads, send a POST request to the /act_ad_account_id/adcreatives endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:

  • access_token
  • name
  • object_story_spec with a *_data object that defines the media type, image or video, and contains:
    • the *_data.page_welcome_message parameter set to the key-value pair
      • ctm_lead_gen_template_id:Your_messenger_lead_gen_template_id

Example ad creative for Messenger Ads for Leads with an Image

Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_AD_ACCOUNT_ID/adcreatives"
    -H "Content-Type: application/json" 
    -d '{
          "access_token": "Your_page_access_token",
          "degrees_of_freedom_spec": {
            "creative_features_spec": {
              "standard_enhancements": { "enroll_status": "OPT_IN" }
            }
          },
          "name": "Your_lead_ad_image_ad_name",
          "object_story_spec": {
            "page_id": "Your_page_id",
            "link_data": {
              "call_to_action": {
                "type": "MESSAGE_PAGE",
                "value": { "app_destination": "MESSENGER" }
              },
              "description": "Sample_description",
              "image_hash": "Your_image_hash", 
              "message": "Sample_message_for_Creative",
              "page_welcome_message": "{ "ctm_lead_gen_template_id": "Your_messenger_lead_gen_template_id" }"
            }
          }
       }'

Example ad creative for Messenger Ads for Leads with a Video

Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
curl -X POST "https://graph.facebook.com/v18.0/act_AD_ACCOUNT_ID/adcreatives"
    -H "Content-Type: application/json" 
    -d '{
          "access_token": "Your_page_access_token",
          "degrees_of_freedom_spec": {
            "creative_features_spec": {
              "standard_enhancements": { "enroll_status": "OPT_IN" }
            }
          },
          "name": "Your_lead_ad_video_ad_name",
          "object_story_spec": {
            "page_id": "your_page_id",
            "video_data": { 
              "call_to_action": {
                "type": "MESSAGE_PAGE",
                "value":{ "app_destination": "MESSENGER" }
              },
              "image_url": "Your_thumbnail_url", 
              "link_description": "Your_link_description ",
              "message": "Sample message for Creative ",
              "page_welcome_message": "{ "ctm_lead_gen_template_id": "Your_messenger_lead_gen_template_id" }",
              "video_id": "Your_video_id" 
            }
          }
       }'

Sponsored Messages are a type of ad that can be sent as a message to any Accounts Center account that has an existing Messenger conversation with your business Facebook Page. You can also include other targeting criteria such as demographics, geographic data, custom audiences, or interests.

Requirements

  • Do not use Custom Audiences to exclude users from receiving Sponsored Messages
  • targeting.publisher_platforms must be messenger only
  • targeting.messenger_positions must be sponsored_messages only
  • targeting.device_platforms must be both mobile and desktop
  • promoted_object must be your business` Facebook Page ID
  • You must specify a payload or a URL for the button
  • You must provide options within the conversation for opting out of receiving messages or blocking messages on both desktop or mobile devices.

Limitation

  • Only CPM with billing_event=IMPRESSIONS and optimization_goal=IMPRESSIONS is supported. Minimum bid varies by country. Learn more.
  • Only text or images with buttons, or quick replies are supported.

    To create an ad creative for a sponsored message, your request should include the object_id parameter set to your Facebook Page's ID, the object_type set to SHARE, the messenger_sponsored_message object with message.text parameter set to the text for the ad and the message.attachment object with the following parameters:

    Messenger Sponsored Message Message Attachment Quick Reference

    Image Ad Creative Example Request

    Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
    curl -X POST "https://graph.facebook.com/v18.0/act_AD_ACCOUNT_ID/adcreatives"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token"
           "object_id": "Your_page_id",
           "object_type": "SHARE",
           "messenger_sponsored_message": {
             "message":{
               "text":"Your_ad_creative_text",
               "attachment":{
                 "type":"template",   
                 "payload":{
                   "template_type":"generic", 
                   "elements":[{
                     "title":"Your_image_text",
                     "image_hash":"Your_image_hash",
                     "buttons":[{
                       "type":"web_url", 
                       "title":"Your_button_text", 
                       "url":"Your_destination_URL"
                     }]
                   }]
                 }
               }
             }
           }
         }'

    Quick Reply Ad Creative Example Request

    To create a Sponsored Message with a Quick Replies message, set the messenger_sponsored_message.message object with text set to your question or directive and a quick_replies array for each quick reply option.

    Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
    curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/adcreatives"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token"
           "object_id": "Your_page_id",
           "object_type": "SHARE",
           "messenger_sponsored_message": {
             "message":{
               "text":"Your_ad_creative_text",
               "quick_replies":[
                 {
                   "content_type": "text",
                   "title": "Your_reply_first_option_reply",
                   "payload": "Information_sent_via_postback_webhook_when_option_1_is_selected"
                 },
                 {
                   "content_type": "text",
                   "title": "Your_reply_second_option_reply",
                   "payload": "Information_sent_via_postback_webhook_when_option_2_is_selected"
                 }
               ]              
             }
           }'

    Ad Creative Example Response

    On success your app receives the following JSON response with the ID for the ad creative.

    {
  "id": "ad_creative_id"
}

    Step 4. Create the Ad

    To create the ad you need to associate the ad creative and the ad set. To create the ad, send a POST request to the /act_ad_account_id/ads endpoint where ad_account_id is the ID for your Meta ad account. Your request must included:

    • access_token
    • adset_id (from Step 2)
    • creative_id (from Step 3)
    • name
    • status

    Ad Account Ads Quick Reference

    Ad with Creative Example Request

    Formatted for readability. Replace bold, italics values, such as ad_account_id, with your values.
    curl -X POST "https://graph.facebook.com/v18.0/act_ad_account_id/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "adset_id": "Your_ad_set_id",
           "creative": { "creative_id": "Your_ad_creative_id" },
           "status": "PAUSED"
         }'

    On success your app receives the following JSON response with the ID for the ad.

    {
  "id": "ad_id"
}

    Step 5. Publish your Ad

    Verify that your ad exists in the ads manager . Click the Review and publish button in the upper right corner. Select your campaign, the ad set for the campaign, and the ad.

    You can publish your ad from the ads manager or using the API. To publish using the API, repeat Step 4 with the status parameter set to ACTIVE.

    Your ad will be reviewed by Meta and the status will be PENDING_REVIEW. Once approved, the status will be ACTIVE and your ad will be delivered.

    Advanced Click to Messenger Elements

    You can create messages that include more than one message element, like a call prompt or multiple templates. You will add these elements by setting an array of objects for the *_data.page_welcome_message value instead of a string value.

    Page Welcome Message Array Quick Reference

    Add a Call Prompt

    You can add a call prompt to your Click to Messenger ad by setting the value of *_data.page_welcome_message to an array of objects that define your call prompt elements. Set the landing_screen_type parameter to call_prompt, media_type to text, and the text_format.message object with text to your welcome message text, and call_prompt_data.call_prompt_message set to a prompt to call your business.

    Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
    ... 
      "page_welcome_message": "[
        {
          "landing_screen_type": "call_prompt",
          "media_type": "text",
          "text_format": {
            "message": {
              "text": "Your_welcome_message",
              "call_prompt_data": { 
                "call_prompt_message": "Your_call_prompt_message"
              }
            }
          },
        }
      ]"
...

    Add One or More Templates

    To create an ad with multiple templates set *_data.page_welcome_message parameter to an array with a message template The following example adds a template for a quick reply.

    Formatted for readability. Replace bold, italics values, such as page_access_token, with your values.
    ... 
      "page_welcome_message": "[{
        'message': {
          'text':'  Your_question_or_directive  ',
          'quick_replies':[
            {
              'content_type':'text',
              'title':'  Option_1  ',
              'payload':'  Option_1_information_for_webhook  '
            },
            {
              'content_type':'text',
              'title':'  Option_2  ',
              'payload':'  Option_2_information_for_webhook  '
            },
            {
              'content_type':'text',
              'title':'  Option_3  ',
              'payload':'  Option_3_information_for_webhook  '
            }
          ]
        }
      }]",
...

    Learn More

    Learn more about the Marketing API and additional options for Click to Messenger and Sponsored Message ads.

    Marketing API

    Messenger Platform