Marketing API

Asset Feed Spec Options

You can use the following options in your asset_feed_spec. See Ad Asset Feed Spec for more reference information.

Property Name Description

images

type: array of list

Required for SINGLE_IMAGE and CAROUSEL_IMAGE format.

Array of eligible images. Images provided in this array should be included in the ad account's image library.


Provide this field as an array of list containing {"url": "{IMAGE_URL}", "hash": "{IMAGE_HASH}", "url_tags": "{TAG}"}. Either url or hash is required.

videos

type: array of list

Required for SINGLE_VIDEO format.

Array of video_ids. The video_ids provided in this array should belong to the ad account.


Provide this field as an array of list containing {"video_id": "{VIDEO_ID}", "thumbnail_url": "{THUMBNAIL_URL}", "url_tags": "{TAG}"}

carousels
type: array of list

Optional.
Array of child_attachments along with the multi_share_end_card and multi_share_optimized Booleans, and adlabels. The child_attachments provided in this array should belong to the ad account.



Provide child_attachments as an array of list containing {"image_label": {"name": "{IMAGE_LABEL}"}, "video_label": {"name": "{VIDEO_LABEL}"}, "title_label": {"name": "{TITLE_LABEL}"}, "description_label": {"name": "{DESC_LABEL}", "link_url_label": {"name": "{LINK_URL}"}}. Either image_label or video_label is required.

bodies

type: array of list

Optional.

Array of bodies. The primary message or copy of the ad.


Provide this field as an array of list of {"text": "{BODY_TEXT}", "url_tags": "{TAG}"}.

call_to_action_types

type: array of list

Required for all objectives, except OUTCOME_AWARENESS.

Array of call-to-action-type values.


Provide this field as an array of list of {"{CALL_TO_ACTION}"}. You can provide multiple values, up to five.

titles

type: array of list

Optional.

Array of titles. A title is a short headline in the ad, generally shown next to a link, image or video.


Provide this field as an array of list of {"text": "{TITLE}", "url_tags": "{TAG}"}.

descriptions

type: array of list

Optional.

Array of secondary description text, displayed less prominently than bodies or titles. Generally appears next to a link, image or video. If not specified, Facebook scrapes the link you provided to generate it. Use an empty string with single space for blank description, if you do not want to use the scraped text.


Provide this field as an array of list of {"text": "{DESCRIPTION}", "url_tags": "{TAG}"}.

link_urls

type: array of list

Required.

Array of link URLs.


Provide this field as an array of list of {"website_url": "{URL}"}.

ad_formats

type: array of strings

Required.

Array of Facebook ad formats we should create the ads in. Supported formats are: SINGLE_IMAGE, CAROUSEL, SINGLE_VIDEO, AUTOMATIC_FORMAT.


Provide this field as an array of strings ["{AD_FORMAT}"].

optimization_type

type: string

Optional.

Optimization type used in asset feed. Possible values are ASSET_CUSTOMIZATION, LANGUAGE, PLACEMENT, and REGULAR.

message_extensions

type: array of strings

Optional.
Message extension type used in asset feed.


Possible value: whatsapp

onsite_destinations
type: array of list

Required for Shops Ads. Valid for Static Ads; SINGLE_IMAGE, SINGLE_VIDEO or CAROUSEL format.
Provide this field as an array of list containing one of the following values to specify the landing destination for your onsite shop.

{"storefront_shop_id": "<SHOP_STOREFRONT_ID>"}
or 
{"shop_collection_product_set_id": "<PRODUCT_SET_ID>" 
or 
{"details_page_product_id": "<PRODUCT_ID>"}

shops_bundle
type: boolean

Required for Shops Ads. Valid for Advantage+ Catalog Ads.
Provide this field for shop optimization. Includes both reasons_to_shop and automated_product_tags shop optimization types.
Possible values: true, false

reasons_to_shop
type: boolean

Required for Shops Ads. Valid for Advantage+ Catalog Ads.
Provide this field for shop optimization. Automatically highlights product information from your shop, like "Free shipping", "Trending" or "Low stock".
Possible values: true, false

Asset Feed Spec Restrictions

Ad Formats

  • Supported ad_formats: SINGLE_IMAGE, CAROUSEL, SINGLE_VIDEO, and AUTOMATIC_FORMAT.
  • Only one ad_format is allowed per asset feed.
  • ad_format counts as one asset in an asset feed.

Number of Assets:

  • Maximum of 30 total assets. For example, you have 28 assets with 10 images, 5 bodies, 5 titles, 5 description, 1 ad_format, 1 link_url, and 1 call_to_action_types.
  • Total number of images: <= 10.
  • Total number of videos: <= 10. If you use Instagram as your placement, only square videos or landscape videos allowed.
  • Total number of bodies: <= 5.
  • Total number of call-to-actions: <= 5.
  • Total number of titles: <= 5.
  • Total number of links: <= 5.
  • Total number of descriptions: <= 5.

Image requirements:

  • Recommended image specs: 1.9:1.
  • Recommended image size: 1,200 x 628 pixels.
  • For CAROUSEL_IMAGE format, you must provide at least 2 images.
  • If you use Instagram as your placement, use square images for better performance.

Text requirements:

  • Title and description text: maximum length of 255 characters.
  • Body text: maximum length of 1024 characters.
  • If you do not specify any description, we scrape the link you provided to retrieve a description.
  • For CAROUSEL_IMAGE, titles are optional.

url_tags are optional and only available for images, videos, bodies, descriptions, and titles. Facebook appends url_tags to the link URL as parameters for each asset in an ad.

For example, a valid asset feed combination setup for SINGLE_IMAGE format is:

  • 5 images
  • 3 bodies
  • 3 titles
  • 3 descriptions
  • 1 format: SINGLE_IMAGE
  • 2 link_urls
"link_urls=[{'website_url':'<WEBSITE_URL>'}, {'website_url':'<WEBSITE_URL>'}]"

Use Deep Links

You can use deeplinks in asset feed specs for campaigns with the following objectives:

  • APP_INSTALLS
  • CONVERSIONS
  • LINK_CLICKS

Add deeplink_url in link_urls when you create your asset_feed_spec.

curl \
-F 'object_story_spec={
       "page_id": "<PAGE_ID>"
       "instagram_actor_id" : "<INSTAGRAM_ACTOR_ID>",
    }' \
-F "asset_feed_spec={'images': [{'hash':'image_hash'}], 'bodies': [{'text':'Body 1'}, {'text':'Body 2'}], 'titles': [{'text':'Title 1'}, {'text':'Title 2'}], 'descriptions': [{'text':' '}], 'ad_formats': ['SINGLE_IMAGE'], 'link_urls': [{'website_url':'App's object store URL','deeplink_url':'deeplink URL'}]}" \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives

Website to WhatsApp Ads

You can create ads that send people to your website with a WhatsApp button appearing at the bottom of the screen, so they can contact you instantly. This will help people connect with you on WhatsApp while visiting your website.

Add message_extensions when you create your asset_feed_spec.

curl \
-F 'object_story_spec={
       "page_id": "<PAGE_ID>"
       "instagram_actor_id" : "<INSTAGRAM_ACTOR_ID>",
    }' \
-F 'asset_feed_spec={"images": [{"hash":"image_hash"}], "bodies": [{"text":"Body 1"}, {"text":"Body 2"}],"titles": [{"text":"Title 1"}, {"text":"Title 2"}], "descriptions": [{"text":" "}], "ad_formats": ["SINGLE_IMAGE"], "link_urls": [{"website_url":"business URL"}], "message_extensions": [{"type": "whatsapp"}]}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adcreatives