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.
To create and publish an ad you will:
This guide assumes you have:
To make successful calls to all endpoints in this guide, you will need:
ADVERTIZE
task on the Pageads_management
pages_manage_ads
pages_read_engagement
pages_show_list
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:
|
|
curl -X POST "https://graph.facebook.com/v21.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" }
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 adspromoted_object
– set to the ID for your business' Facebook Page.status
set to PAUSED
targeting
curl -X POST "https://graph.facebook.com/v21.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" }
The ad creative allows you to add assets to your ads.
Limitations
|
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
– Requiredprivacy_url
– Required for lead adsstandard_enhancements.enroll_status
– Required for ad creatives that are eligible for standard enhancements. Top Level Ad Creative Parameter Quick Reference
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
curl -X POST "https://graph.facebook.com/v21.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
curl -X POST "https://graph.facebook.com/v21.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/v21.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"
}
}
}'
For more information about messaging app flows, refer to Welcome message flows in the Messenger Platform documentation.
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.
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" }
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
*_data
object that defines the media type 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
curl -X POST "https://graph.facebook.com/v21.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"
}]
}]
}
}
}
}
}"
}
}
}'
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.
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
curl -X POST "https://graph.facebook.com/v21.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.
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.
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:
*_data.page_welcome_message
parameter set to the key-value pair
ctm_lead_gen_template_id:
Your_messenger_lead_gen_template_id
curl -X POST "https://graph.facebook.com/v21.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/v21.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"
}
}
}'
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/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
curl -X POST \
-F 'name=Sample ad creative from Instagram image' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACTOR_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/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
Refer to Use Posts as Instagram Ads: Facebook Posts for more details.
curl -i -X POST \
"https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT>/adcreatives
?object_story_id=<postOwnerID_postID>
&instagram_actor_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_actor_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.
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:
Ad Account Ads Quick Reference
curl -X POST "https://graph.facebook.com/v21.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" }
You can also set a call to action when creating your ad.
"call_to_action": { "value": {"app_destination":"MESSENGER"}, "type": "MESSAGE_PAGE" }
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.
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
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" } } }, } ]" ...
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 ' } ] } }]", ...
If you have not already, set up webhooks to get notifications for when a person clicks on your ad.
Learn more about the Marketing API and additional options for Click to Messenger.