This guide explains how to create and publish ads that click to Instagram using the Marketing API.
Ads that click to Instagram Direct send people that click on your ads directly into conversations with your business in Instagram Direct. Use these ads to reach people at scale and deliver standout, individualized service.
Ads that click to Instagram 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 Messenger or WhatsApp chats, see Ads that Click to Messenger and 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.
This document outlines the steps you need to follow to set up your integration for click to Instagram ads. You will need to:
This guide assumes you have:
To make successful calls to all endpoints in this guide, you will need:
ads_management
pages_manage_ads
pages_read_engagement
pages_show_list
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. |
enum | Required. |
list<Object> | Required. |
enum | Optional. |
curl -X POST \
-F 'name=Click to Instagram Campaign' \
-F 'objective=OUTCOME_ENGAGEMENT' \
-F 'status=ACTIVE' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.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 Instagram 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/v21.0
/<AD_CAMPAIGN_ID>
{ "name": "Click to Instagram 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:
Name | Description |
---|---|
unsigned int32 | Required if bid_strategy is set to |
enum | Optional. |
enum | Required. |
numeric string or integer | Required. |
int64 | Required if |
string | Required.
Set to |
datetime | Required when |
int64 | Required if |
string | Required. |
enum | Required.
|
| Required.
See Ad Set, Promoted Object for more details. |
datetime | Optional. |
enum | Optional. |
Targeting object | Required. |
datetime | Optional. |
datetime | Required when |
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=<AD_CAMPAIGN_ID>' \ -F 'daily_budget=<DAILY_BUDGET>' \ -F 'destination_type=INSTAGRAM_DIRECT' \ -F 'name=Click to Instagram Ad Set' \ -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/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets
{ "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 Instagram 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,status' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<AD_SET_ID>
{ "name": "Click to Instagram Ad Set", "destination_type": "INSTAGRAM_DIRECT", "optimization_goal": "CONVERSATIONS", "bid_strategy": "LOWEST_COST_WITHOUT_CAP", "status": "ACTIVE", "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:
Name | Description |
---|---|
string | Required. |
| Required. Required:
Optional:
|
| Optional. |
Visit th Ad Creative reference for the complete list of available parameters.
If you see the error “Creative Must Provide enroll_status for Standard Enhancements” on v17.0+, refer to Standard Enhancements for Advantage+ Creative and fix it.
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 Instagram by customizing your ads' greeting message in the page_welcome_message
field under object_story_spec
.
Adding text icebreakers with an optional automated response. String interpolation {{user_first_name}}
, {{user_last_name}}
, {{user_full_name}}
, and {{page_name}}
can be used in the greeting message and automated response. For example, “Hi {{user_first_name}}. Welcome to {{page_name}}!”
"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": "<GREETING_MESSAGE>", "ice_breakers": [ { "title": "<ICEBREAKER>", "response": "<AUTO_RESPONSE>" }, { "title": "<ICEBREAKER>", "response": "<AUTO_RESPONSE>" }, { "title": "<ICEBREAKER>", "response": "<AUTO_RESPONSE>" } ] } } }
Refer to Ad, Image for more details.
curl -X POST \
-F 'name=Sample ad creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACCOUNT_ID>",
"link_data": {
"message": "<AD_PRIMARY_TEXT>",
"image_hash": "<IMAGE_HASH>"
"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 Video and Carousel Ads for more details.
curl -X POST \
-F 'name=Sample ad creative' \
-F 'object_story_spec={
"message": "<AD_PRIMARY_TEXT>",
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACCOUNT_ID>",
"video_data": {
"video_id": "<VIDEO_ID>",
"image_url": "<THUMBNAIL_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
curl -X POST \ -F 'name=Sample ad creative' \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "instagram_actor_id": "<INSTAGRAM_ACCOUNT_ID>", "link_data": { "message": "<AD_PRIMARY_TEXT>", "image_hash": "<IMAGE_HASH>" "call_to_action": { "type": "INSTAGRAM_MESSAGE", "value": { "app_destination": "INSTAGRAM_DIRECT" } } } }' \ -F 'asset_feed_spec={ "additional_data": { "partner_app_welcome_message_flow_id": "<FLOW_ID>", } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/adcreatives
For more information about messaging app flows, refer to Welcome message flows in the Messenger Platform documentation.
Refer to Video and Carousel Ads for more details.
curl -X POST \
-F 'name=Sample ad creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"instagram_actor_id": "<INSTAGRAM_ACCOUNT_ID>",
"link_data": {
"message": "<AD_PRIMARY_TEXT>",
"page_welcome_message": "<PAGE_WELCOME_MESSAGE>",
"call_to_action": {
"type": "INSTAGRAM_MESSAGE",
"value": {
"app_destination": "INSTAGRAM_DIRECT"
}
},
"child_attachments": [
{
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "INSTAGRAM_MESSAGE",
"value": {
"app_destination": "INSTAGRAM_DIRECT"
}
},
"name": "<AD_HEADLINE>"
},
{
"video_id": "<VIDEO_ID>",
"picture": "<THUMBNAIL_URL>",
"call_to_action": {
"type": "INSTAGRAM_MESSAGE",
"value": {
"app_destination": "INSTAGRAM_DIRECT"
}
},
"name": "<AD_HEADLINE>"
}
],
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.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/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.
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 Instagram 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{link_data{call_to_action,page_welcome_message}}' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<AD_CREATIVE_ID>
{ "name": "Sample ad creative", "object_story_spec": { "link_data": { "call_to_action": { "type": "INSTAGRAM_MESSAGE", "value": { "app_destination": "INSTAGRAM_DIRECT" } }, "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 1" }, { "title": "Sample icebreaker 2" }, { "title": "Sample icebreaker 3" } ] } } } } }, "id": "<AD_CREATIVE_ID>" }
Use this API to get connected Instagram accounts with the Instagram Account Backed Page ID (IABP ID).
curl -X GET \
-F 'fields="iabp_id"' \
-F 'business_id=<BUSINESS_ID>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/connected_instagram_accounts_with_iabp
Then when you use post as ads, you can use the IABP ID as the value of object_id
.
curl -i -X POST \
"https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT>/adcreatives
?object_id=<IABP_ID> // iabp_id instead of page_id
&instagram_user_id=<IG_USER_ID>
&source_instagram_media_id=<IG_ORGANIC_MEDIA_ID>
&access_token=<API_ACCESS_TOKEN>"
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. |
numeric string or integer | Required. |
| Required. |
enum | Required. |
curl -X POST \
-F 'name=Click to Instagram Ad' \
-F 'adset_id=<AD_SET_ID> \
-F 'creative={
"creative_id": "<AD_CREATIVE_ID>"
}' \
-F 'status=PAUSED \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/ads
{ "id": "<AD_ID>" }
You can also set a call to action when creating your ad.
"call_to_action": { "value": {"app_destination":"INSTAGRAM_DIRECT"}, "type": "MESSAGE_PAGE" }
You can update an ad by making a POST
request to /<AD_ID>
.
To verify that you have successfully created a click to Instagram 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,campaign_id \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<AD_ID>
{ "status": "PAUSED", "adset_id": "<AD_SET_ID>", "campaign_id": "<AD_CAMPAIGN_ID>", "id": "<AD_ID>" }
Verify your ad exists in Ads Manager. When you are ready to publish your changes, select your campaign, the ad set for the campaign, and the ad, and click the Publish button.
You can also publish your ad using the API by sending a POST
request to /<AD_ID>
with the status
parameter set to ACTIVE
where <AD_ID>
is the ad you want to publish.
curl -X POST \
-F 'status=ACTIVE' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<AD_ID>
{ "success": true }
Your ad will be reviewed by Meta, and the effective_status
will be PENDING_REVIEW
. Once approved, the status will automatically update to ACTIVE
, and your ad will be delivered.
curl -X GET -G \
-d 'fields=status,effective_status' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/<AD_ID>
{ "status": "ACTIVE", "effective_status": "PENDING_REVIEW", "id": "<AD_ID>" }