This guide explains how to create and publish ads that click to multidestination using the Marketing API.
Ads that click to multidestination send people that click on your ads directly into conversations with your business in the messaging app or apps (Messenger, Instagram, or WhatsApp) that they are most likely to respond from. Use these ads to reach people at scale and deliver standout, individualized service.
Multidestination ads means the ad can go to any combination of the destinations: Messenger chat, Instagram chat, WhatsApp chat.
If you’d like to create an ad that only goes to one destination, see:
This document outlines the steps you need to follow to set up your integration for click to multidestination ads. You will need to:
This guide assumes you have:
Start by creating your ad campaign. To do this, make 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:
Name | Description |
---|---|
string
|
Required.Name for the click to mutlidestination campaign. |
enum
|
Required. |
list<Object>
|
Required. |
enum
|
Optional. |
curl -X POST \
-F 'name=Click to Multi Destination Campaign' \
-F 'objective=OUTCOME_ENGAGEMENT' \
-F 'status=ACTIVE' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/act_<AD_ACCOUNT_ID>/campaigns
On success, your app receives a JSON response with the ID of your newly created campaign.
{ "id": "<AD_CAMPAIGN_ID>" }
You can update a campaign by making a POST
request to /<AD_CAMPAIGN_ID>
.
To verify that you have successfully created a click to multidestination campaign, you can make a GET
request to /<AD_CAMPAIGN_ID>
. See the Ad Campaign reference
for the complete list of available parameters.
curl -X GET -G \
-d 'fields=name,status,objective' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/<AD_CAMPAIGN_ID>
{ "name": "Click to Multi Destination Campaign", "status": "ACTIVE", "objective": "OUTCOME_ENGAGEMENT", "id": "<AD_CAMPAIGN_ID>" }
Once you have an ad campaign, create your ad set. To create an ad set, make 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:
bid_amount
Requiredif bid_strategy is set to LOWEST_COST_WITH_BID_CAP
or COST_CAP
.
The maximum amount you want to pay for a result based on your optimization_goal
.
bid_strategy
Optional.
The bid strategy for this campaign to suit your specific business goals. See the Ad Campaign reference
for more details.
Values: LOWEST_COST_WITHOUT_CAP
, LOWEST_COST_WITH_BID_CAP
, COST_CAP
billing_event
Required.
Must be set to IMPRESSIONS
for ads that click to multidestination. Meta bills you when your ad is shown to people.
campaign_id
Required.A valid click to multidestination campaign you wish to add this ad set to.
daily_budget
Requiredif lifetime_budget
is not set.
The daily budget defined in your account currency. Allowed only for ad sets with a duration (difference between end_time
and start_time
) longer than 24 hours.
Either daily_budget
or lifetime_budget
must be greater than 0
.
destination_type
Required.
MESSAGING_INSTAGRAM_DIRECT_MESSENGER_WHATSAPP
if you want to use all three destinations (Messenger, WhatsApp, and Instagram).MESSAGING_INSTAGRAM_DIRECT_MESSENGER
if you want to use Messenger and Instagram.MESSAGING_MESSENGER_WHATSAPP
if you want to use Messenger and WhatsApp.MESSAGING_INSTAGRAM_DIRECT_WHATSAPP
if you want to use WhatsApp and Instagram.Note:If you include WhatsApp in the destinations, please make sure you have WhatsApp business number connected to your page. If you include Instagram in the destinations, please make sure you have Instagram business account connected to your page.
end_time
Requiredwhen lifetime_budget
is specified.
When creating an ad set with a daily_budget
, specify end_time=0
or leave this field empty to set the ad set as ongoing with no end date.
Example: 2015-03-12 23:59:59-07:00
or 2015-03-12 23:59:59 PDT
. UTC UNIX timestamp.
lifetime_budget
Requiredif daily_budget
is not set.
The lifetime budget of the ad set defined in your account currency. If specified, you must also specify an end_time
.
Either daily_budget
or lifetime_budget
must be greater than 0
.
name
Required.The name of the click to multidestination ad set.
optimization_goal
Required.
What the ad set is optimizing for. Must be set to CONVERSATIONS
for ads that click to multidestination. Depending on the campaign’s objective, the ad set may be eligible for different optimization goals.
promoted_object
Required.
The object this ad set is promoting across all its ads. For ads that click to multidestination, promoted_object
has the following conditions:
page_id
: Required.The ID of the Facebook Page.See Ad Set, Promoted Object for more details.
start_time
Optional.
The start time of the ad set. This field will default to the current time if no value is provided.
Example: 2015-03-12 23:59:59-07:00
or 2015-03-12 23:59:59 PDT
. UTC UNIX timestamp.
status
Optional.
The status of the ad set. It can be different from the effective status due to its parent campaign. This field will default to ACTIVE
if no value is provided.
Vales: ACTIVE
, PAUSED
, DELETED
, ARCHIVED
targeting
Required.
The targeting structure of an ad that clicks to Instagram. See Targeting
for more details.
time_start
Optional.
Interchangeable with start_time
.
time_stop
Requiredwhen lifetime_budget
is specified.
Interchangeable with end_time
.
Visit the Ad Account Ad Set reference for the complete list of available parameters.
curl -X POST \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'bid_strategy=LOWEST_COST_WITHOUT_CAP' \
-F 'billing_event=IMPRESSIONS' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'daily_budget=<DAILY_BUDGET>' \
-F 'destination_type=<DESTINATION_TYPE>' \
-F 'name=<AD_SET_NAME>' \
-F 'optimization_goal=CONVERSATIONS' \
-F 'promoted_object={
"page_id": "<PAGE_ID>"
}' \
-F 'status=ACTIVE' \
-F 'start_time=<START_TIME>' \
-F 'targeting={
"geo_locations": { "countries":["US","CA"] },
"device_platforms": ["mobile", "desktop"]
}' \
https://graph.facebook.com/ v20.0
/act_<AD_ACCOUNT_ID>/adsets
On success, your app receives a JSON response with the ID of your newly created ad set.
{ "id": "<AD_SET_ID>" }
You can update an ad set by making a POST
request to /<AD_SET_ID>
.
To verify that you have successfully created a click to multidestination ad set, you can make a GET
request to /<AD_SET_ID>
. See the Ad Set reference
for the complete list of available parameters.
curl -X GET -G \
-d 'fields=name,destination_type,optimization_goal,bid_strategy' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/<AD_SET_ID>
{ "name": "<AD_SET_NAME>", "destination_type": "<DESTINATION_TYPE>", "optimization_goal": "CONVERSATIONS", "bid_strategy": "LOWEST_COST_WITHOUT_CAP'" "id": "<AD_SET_ID>" }
The ad creative allows you to add assets to your ads. To create an ad creative, make 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:
asset_feed_spec
Required.Specify the destinations of ads that click to Multi Destination
Required:
optimization_type
: Must be set to DOF_MESSAGING_DESTINATION
for ads that click to multidestination.call_to_actions
: Array of the selected destinations of ads that click to multidestination. It needs to match with the destination_type
specified in the ad set.Messenger
{ "type": "MESSAGE_PAGE", "value": { "app_destination": "MESSENGER", "link": "https://fb.com/messenger_doc/" } }
{ "type": "WHATSAPP_MESSAGE", "value": { "app_destination": "WHATSAPP", "link": "https://api.whatsapp.com/send" } }
{ "type": "INSTAGRAM_MESSAGE", "value": { "app_destination": "INSTAGRAM_DIRECT", "link": "https://www.instagram.com" } }
name
Required.The name for your ad creative.
object_story_spec
Required.
An object containing information about a message. See Ad Creative Object Story Spec
for more details.
Required:
page_id
: The ID of the Facebook Pageinstagram_actor_id
: Instagram Account ID. There are three ways to obtain an Instagram account ID
: Business Manager owned Instagram account, Page connected Instagram account, and Page backed Instagram account.Optional:
link_data
: The spec for a link page post or carousel ad
photo_data
: The spec for a photo page posttext_data
: The spec for a text page postvideo_data
: The spec for a video page post degrees_of_freedom_spec
Optional.
See Standard Enhancements for Advantage+ Creative
for more details.
Visit th Ad Creative reference for the complete list of available parameters.
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 multidestination 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" }
Add the page_welcome_message
field to the creative as follows.
curl -X POST \
-F 'name=<CREATIVE_NAME>' \
-F 'object_story_spec={
"page_id": "438346666550309",
"link_data": {
"name": "<AD_HEADLINE>",
"message": "<AD_PRIMARY_TEXT>",
"image_hash": "<IMAGE_HASH>"
"link": "https://fb.com/messenger_doc/",
"page_welcome_message": "<PAGE_WELCOME_MESSAGE>",
"call_to_action": {
"type": "MESSAGE_PAGE",
"value": {
"app_destination": "MESSENGER"
}
}
}
}' \
-F 'asset_feed_spec={
"optimization_type": "DOF_MESSAGING_DESTINATION",
"call_to_actions": [
{
"type": "MESSAGE_PAGE",
"value": {
"app_destination": "MESSENGER",
"link": "https://fb.com/messenger_doc/"
}
},
{
"type": "WHATSAPP_MESSAGE",
"value": {
"app_destination": "WHATSAPP",
"link": "https://api.whatsapp.com/send"
}
},
{
"type": "INSTAGRAM_MESSAGE",
"value": {
"app_destination": "INSTAGRAM_DIRECT",
"link": "https://www.instagram.com"
}
}
]
}' \
-F 'degrees_of_freedom_spec={
"creative_features_spec": {
"standard_enhancements": {
"enroll_status": "OPT_IN"
}
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/act_<AD_ACCOUNT_ID>/adcreatives
On success, your app receives a JSON response with the ID of your newly created ad creative.
{ "id": "<AD_CREATIVE_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/ v20.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/ v20.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/ v20.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
.
You can update an ad creative
by making a POST
request to /<AD_CREATIVE_ID>
.
To verify that you have successfully created a click to multidestination ad creative, you can make a GET
request to /<AD_CREATIVE_ID>
. See Ad Creative
for the complete list of available parameters.
curl -X GET -G \
-d 'fields=name,object_story_spec{page_welcome_message},asset_feed_spec' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/<AD_CREATIVE_ID>
{ "name": "<CREATIVE_NAME>", "object_story_spec": { "page_welcome_message": { "type": "VISUAL_EDITOR", "version": 2, "landing_screen_type": "welcome_message", "media_type": "text", "text_format": { "customer_action_type": "ice_breakers", "message": { "text": "Sample greeting message", "ice_breakers": [ { "title": "Sample icebreaker" }, { "title": "Sample icebreaker" }, { "title": "Sample icebreaker" } ] } } } }, "asset_feed_spec": { "optimization_type": "DOF_MESSAGING_DESTINATION", "call_to_actions": [ { "type": "MESSAGE_PAGE", "value": { "app_destination": "MESSENGER", "link": "https://fb.com/messenger_doc/" } }, { "type": "WHATSAPP_MESSAGE", "value": { "app_destination": "WHATSAPP", "link": "https://api.whatsapp.com/send" } }, { "type": "INSTAGRAM_MESSAGE", "value": { "app_destination": "INSTAGRAM_DIRECT", "link": "https://www.instagram.com" } } ] }, "id": "<AD_CREATIVE_ID>" }
Ads allow you to associate ad creative information with your ad sets. To create an ad, make 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 include:
Name | Description |
---|---|
string
|
Required.The name for your ad creative. |
numeric string or integer
|
Required.The ID of the ad set. |
|
Required. |
enum
|
Required. |
curl -X POST \
-F 'name=<AD_NAME>' \
-F 'adset_id=<AD_SET_ID> \
-F 'creative={
"creative_id": "<AD_CREATIVE_ID>"
}' \
-F 'status=ACTIVE \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/act_<AD_ACCOUNT_ID>/ads
On success, your app receives a JSON response with the ID of your newly created ad.
{ "id": "<AD_ID>" }
You can also set a call to action when creating your ad.
"asset_feed_spec": { "optimization_type": "DOF_MESSAGING_DESTINATION", "call_to_actions": [ { "type": "MESSAGE_PAGE", "value": { "app_destination": "MESSENGER", "link": "https://fb.com/messenger_doc/" } }, { "type": "INSTAGRAM_MESSAGE", "value": { "app_destination": "INSTAGRAM_DIRECT", "link": "https://www.instagram.com" } } ] }
See the Asset Feed Spec documentation for more information.
You can update an ad
by making a POST
request to /<AD_ID>
.
To verify that you have successfully created a click to multidestination ad, you can make a GET
request to /<AD_ID>
. See the ad reference
for the complete list of available parameters.
curl -X GET -G \
-d 'fields=status,adset_id \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/ v20.0
/<AD_ID>
{ "status": "ACTIVE", "adset_id": "<AD_SET_ID>", "id": "<AD_ID>" }