Ads that Click to Messenger

This guide explains how to create and publish ads that click to Messenger using the Marketing API.

If you would like to use the Ads Manager to create a campaign for lead ads, visit the Meta Business Help Center.

Ads that click to Messenger send people that click on your ads directly into conversations with your business in Messenger. Use these ads to reach people at scale and deliver standout, individualized service.

Ads that click to Messenger support ads with an image, a video, a carousel, or a slideshow. You can also include call prompts in your ad.

If you’re interested in creating ads that send people to Instagram or WhatsApp chats, see Ads that Click to Instagram or Ads that Click to WhatsApp for guidance. You can also create ads that pick the destination the user is most likely to respond from, see Ads that Click to Multidestination for more information.

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

Before You Start

This guide assumes you have:

• An ad account with Meta
• The Messenger Platform integrated into your app or website
• Uploaded any assets, such as images or videos, to be used in your ads to Meta servers

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 by your app user:
  • 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:

Ad Campaign Quick Reference

• Visit our Ad Account Campaign Endpoint Reference for the complete list of available parameters.

Example Request

curl -X POST "https://graph.facebook.com/v24.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.
• status set to PAUSED
• targeting

Ad Set Quick Reference

Visit our Ad Account Ad Set Endpoint Reference for the complete list of available parameters.

Example Request

curl -X POST "https://graph.facebook.com/v24.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
• name
• object_story_spec – Required
• privacy_url – Required for lead ads
• standard_enhancements.enroll_status – Required for ad creatives that are eligible for standard enhancements.

Ad Creative Quick Reference

Parameter	Value
access_token	Your Page access token. Required
name	The name for your ad creative. For example, "Click to Messenger for September", etc. Required
object_story_spec	An object containing information about a message. Required for Click to Messenger or Click to Subscribe ads link_data – An object defining a message with a template or carousel page_id – Required. The ID for the Facebook Page sending the message photo_data – An object defining a message with an image text_data – An object defining a message with text only video_data – An object defining a message with a video
privacy_url	Set to the URL for your privacy policy. Required for Messenger Ads for Leads

curl -X POST "https://graph.facebook.com/v24.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" }
               }   
             }
           }
         }'          

curl -X POST "https://graph.facebook.com/v24.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"
             } 
           }
         }'

curl -X POST "https://graph.facebook.com/v24.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": { 
               "image_hash": "your_image_hash",
               "link": "your_image_URL",
               "call_to_action": {
                 "type": "MESSAGE_PAGE",
                 "value": { "app_destination":"MESSENGER" }
               }   
             }
           },
           "asset_feed_spec": {
             "additional_data": {
               "partner_app_welcome_message_flow_id": "FLOW-ID"
             }
           }
         }'

Filling out Page Welcome Message

The default message that a customer sees is "Hello! Can I get more info on this?". You can create more tailored user experiences for your ads that click to Messenger by customizing your ads' greeting message, icebreakers, and autofill messages in the page_welcome_message field under object_story_spec.

For more information about icebreakers, see the ice_breakers reference.

Limitations

• Icebreaker titles must not be more than 80 characters.
• Icebreaker responses must not be more than 300 characters.
• Message text must not be more than 300 characters.

Example

Create the page_welcome_message object to add icebreakers with a greeting message.

"page_welcome_message": {
  "type":"VISUAL_EDITOR",
  "version":2,
  "landing_screen_type":"welcome_message",
  "media_type":"text",
  "text_format":{
    "customer_action_type":"ice_breakers",
    "message":{
      "ice_breakers":[
        {"title":"Can I make a purchase?","response":"This is a response 1"},
        {"title":"Can I see a menu?", "response":"This is a response 2"},
        {"title":"Where are you located?", "response":"This is a response 3"}],
      "quick_replies":[],
      "text":"Hi {{user_first_name}}! Please let us know how we can help you."}
  },
  "user_edit":false,
  "surface":"visual_editor_new"
}

curl -X POST "https://graph.facebook.com/v24.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"
                             }]
                         }]
                       }
                     }
                   } 
                 }
               }"
             }
           }
         }'          

curl -X POST "https://graph.facebook.com/v24.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"
             }
           ]
        }'

{
  "id": "your_messenger_lead_gen_template_id"
}

curl -X POST "https://graph.facebook.com/v24.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" }"
            }
          }
       }' 

curl -X POST "https://graph.facebook.com/v24.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" 
            }
          }
       }' 

Creating ad creatives using Instagram content

Instagram Posts

Refer Use Posts as Instagram Ads for more details.

curl -X POST \
  -F 'name=Sample ad creative from Instagram post' \
  -F 'object_id=<PAGE_ID>' \
  -F 'instagram_user_id=<INSTAGRAM_USER_ID>' \
  -F 'source_instagram_media_id=<INSTAGRAM_POST_ID>' \
  -F 'call_to_action={
       "type": "INSTAGRAM_MESSAGE",
       "value": {
         "link": "https://www.instagram.com"
       }
     }' \ 
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives

Instagram Images

curl -X POST \
  -F 'name=Sample ad creative from Instagram image' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "instagram_user_id": "<IG_USER_ID>",
       "link_data": {
         "message": "<AD_PRIMARY_TEXT>",
         "picture": "<IMAGE_URL>"
         "page_welcome_message": "<PAGE_WELCOME_MESSAGE>",
         "call_to_action": {
           "type": "INSTAGRAM_MESSAGE",
           "value": {
             "app_destination": "INSTAGRAM_DIRECT"
           }
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/act_<AD_ACCOUNT_ID>/adcreatives

Creating ad creatives using Facebook content

Refer to Use Posts as Instagram Ads: Facebook Posts for more details.

curl -i -X POST \
  "https://graph.facebook.com/v24.0/act_<AD_ACCOUNT>/adcreatives
  ?object_story_id=<postOwnerID_postID>
  &instagram_user_id=<IG_USER_ID>
  &call_to_action="{'type':MESSAGE_PAGE,'value':{'app_destination':'MESSENGER'}}"
  &access_token=<ACCESS_TOKEN>"

Where object_story_id is the post ID in the format of postOwnerID_postID and instagram_user_id is either a Page-connected Instagram account ID or the Page-backed Instagram account ID. See more details in Set Up Instagram Accounts With Pages.

Add Product Extensions to Click to Messenger

What is click to messenger with product extensions

Product extensions(the "Show product" feature in Meta Ads Manager) is an Advantage+ creative optimization that showcases products from your catalog below your static single media when it's likely to improve performance. This document shows you how to use product extensions features for Click-to-Messenger ads. If you want to learn how to add product extensions for non-click-to-messenger ads, please refer to this page.

Reference

Eligibility Criteria

• You must have a catalog connected to a shop on Facebook
• A catalog should have at least 1 product item
• Campaign with OUTCOME_ENGAGMENET, OUTCOME_LEAD,OUTCOME_SALES or LINK_CLICK objective
• Single image or video ad format or Facebook existing post content

Create with a single image

curl -X POST "https://graph.facebook.com/v24.0/act_ad_account_id/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "creative_sourcing_spec": {
              "associated_product_set_id": "Your_associated_product_set_id"
            },
            "degrees_of_freedom_spec": {
              "creative_features_spec": {
                "product_extensions": {
                   "enroll_status": "OPT_IN"
                }
              }
            },
            "object_story_spec": {
              "page_id": Your_facebook_page_id",
              "link_data": {
                "call_to_action": {
                  "type": "MESSAGE_PAGE",
                  "value": {
                    "app_destination": "MESSENGER"
                  }
                },
                "image_hash":"Your_image_hash", (or “picture”: "Your_picture_url")"
                "link": "https://fb.com/messenger_doc/",
                "name": "Chat in Messenger"
              },
              "product_data": [
                {
                  "product_id": Your_product_id_1",
                  "product_source": "MANUAL",
		"product_decision": "ACCEPT"
                },
                {
                  "product_id":Your_product_id_2",
                  "product_source": "MANUAL",
		"product_decision": "ACCEPT"
                }
              ]
            }

Create with a single video

curl -X POST "https://graph.facebook.com/v24.0/act_ad_account_id/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "creative_sourcing_spec": {
              "associated_product_set_id": "Your_associated_product_set_id"
            },
            "degrees_of_freedom_spec": {
              "creative_features_spec": {
                "product_extensions": {
                   "enroll_status": "OPT_IN"
                }
              }
            },
            "object_story_spec": {
              "page_id": "Your_facebook_page_id",
              "video_data": {
                "video_id":"Your_video_id"",
                "video_thumbnail_id": "0",
                "call_to_action": {
                  "type": "MESSAGE_PAGE",
                  "value": {
                    "app_destination": "MESSENGER",
                    "link": "https://fb.com/messenger_doc/"
                  }
                },
                "image_url": "Your_image_url",
                "title": "Chat in Messenger",
                "video_thumbnail_source": "generated_default"
              },

              "product_data": [
                {
                  "product_id": Your_product_id_1",
                  "product_source": "MANUAL",
		"product_decision": "ACCEPT"
                },
                {
                  "product_id":Your_product_id_2",
                  "product_source": "MANUAL",
		"product_decision": "ACCEPT"
                }
              ]
            }

Create with a facebook existing post with photo/video media type

curl -X POST "https://graph.facebook.com/v24.0/act_ad_account_id/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "object_story_id": "Your_object_story_id(pageID_postID)",
           "creative_sourcing_spec": {
              "associated_product_set_id": "Your_associated_product_set_id"
            },
            "degrees_of_freedom_spec": {
              "creative_features_spec": {
                "product_extensions": {
                  "enroll_status": "OPT_IN"
                },
                "multi_photo_to_video": {
                  "enroll_status": "OPT_IN"
                }
              }
            },
            "product_data": [
              {
                "product_id": Your_product_id_1",
                "product_source": "MANUAL",
		"product_decision": "ACCEPT"
              },
              {
                "product_id":Your_product_id_2",
                "product_source": "MANUAL",
		"product_decision": "ACCEPT"
              }
            ]
          }

Create with a facebook existing post with album media type

curl -X POST "https://graph.facebook.com/v24.0/act_ad_account_id/ads"
     -H "Content-Type: application/json" 
     -d '{
           "access_token": "Your_page_access_token",
           "object_story_id": "Your_object_story_id(pageID_postID)",
           "creative_sourcing_spec": {
              "associated_product_set_id": "Your_associated_product_set_id"
            },
            "degrees_of_freedom_spec": {
              "creative_features_spec": {
                "product_extensions": {
                   "enroll_status": "OPT_IN"
                }
              }
            },
            "product_data": [
              {
                "product_id": Your_product_id_1",
                "product_source": "MANUAL"
		"product_decision": "ACCEPT"
              },
              {
                "product_id":Your_product_id_2",
                "product_source": "MANUAL"
		"product_decision": "ACCEPT"
              }
            ]
          }

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

curl -X POST "https://graph.facebook.com/v24.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"
}

Call to action

You can also set a call to action when creating your ad.

"call_to_action": {
  "value": {"app_destination":"MESSENGER"},
  "type": "MESSAGE_PAGE"
}

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.

... 
      "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.

... 
      "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  '
            }
          ]
        }
      }]",
...

Next steps

If you have not already, set up webhooks to get notifications for when a person clicks on your ad.

Learn More

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

Marketing API

• Ad Campaign Reference
• Ad Creative Reference
• Ad Reference
• Ad Set Reference
• Audience Targeting Reference
• Create a Form for a Leads Ad
• Get Started with the Marketing API
• Get Leads Generated by Ads
• Optimization Goals and Bidding Events Overview

Messenger Platform

• Message Templates Reference
• Message Lead Forms Reference