Meta / Facebook Developer Docs Mirror

Appearance

Mirrored from https://developers.facebook.com/documentation/ads-commerce/marketing-api/creative/collection-ads

Instant Experiences ​

Updated: May 21, 2026

Instant Experiences are a full-screen, post-click ad destination that loads nearly instantaneously from ads in Feed.

If you see any mentions of canvas in the API, it is a reference to Instant Experiences. Canvas was the previous name of this format.

Before you start ​

To create and manage Instant Experiences, you need:

Limitations ​

  • You can only update an unpublished Instant Experience.
  • The Instant Experiences API is available for Instagram on a limited basis.
  • Ads using Instant Experiences are not supported for Facebook Stories.

Create ​

To create an Instant Experience, you will need the ID of a Facebook Page (PAGE-ID) and any elements, such as photos, buttons, and text, you wish to include in your experience.

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<PAGE_ID>/canvases

Elements ​

NameDescription
ButtonA button within an Instant Experience. The button_style field is required.
CarouselA carousel for the Instant Experience.
FooterA footer for the Instant Experience.
HeaderA header for the Instant Experience.
PhotoA photo within an Instant Experience. You should provide a PHOTO-ID for a photo uploaded to a Facebook Page.
Product ListA list of products for an Instant Experience.
Product SetA set of products from an Advantage+ catalog ads product catalog that are displayed in an Instant Experience.
Store LocatorA store locator within an Instant Experience.
TextThe text and its styling displayed within an Instant Experience.
VideoA video within an Instant Experience. You should provide a VIDEO-ID for a video uploaded to a Facebook Page.

Delete an element ​

To delete an element, send a DELETE request with the ID of the element you wish to delete.

curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<CANVAS_ELEMENT_ID>

Get an existing Instant Experience ​

To get information about an existing Instant Experience, you will need the ID of the Instant Experience (CANVAS-ID).

curl -G \
  --data-urlencode 'fields=[
    "body_elements",
    "canvas_link",
    "id",
    "is_hidden",
    "is_published",
    "name"
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<CANVAS_ID>

Get all Instant Experiences for a Page ​

To get information about all existing Instant Experiences for a Facebook Page, you will need the ID of the Page (PAGE-ID).

curl -G \
  --data-urlencode 'fields=[
    "background_color",
    "body_elements",
    "canvas_link",
    "id",
    "is_hidden",
    "is_published",
    "last_editor",
    "name",
    "owner",
    "update_time"
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<PAGE_ID>/canvases

Update an Instant Experience ​

To update an Instant Experience, the experience must be unpublished and you will need the ID of the Instant Experience (CANVAS-ID) and any element IDs you want to update.

curl \
  -F 'background_color=FFFFFF' \
  -F 'body_element_ids=["<CANVAS_PHOTO_ID>"]' \
  -F 'is_hidden=' \
  -F 'is_published=' \
  -F 'name=Canvas Name' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<CANVAS_ID>

Use a Template ​

You can use a template as a quick way to create an Instant Experience for a specific business goal. The layout for each template is fixed, however you can replace default content with your own images, videos, products, text, and links.

API Template NameTemplate IDDescription
Get New Customers133471657203838Drive conversions with a mobile landing page that encourages action. Customer Acquisition template⁠ in the Ads Manager.
Showcase Your Business1063217037112304Give people an engaging way of exploring your brand, product, or service. Storytelling template⁠ in Ads Manager.
Sell Products (Without Catalog)424787857903852Create a mobile shopping experience by uploading your product information instead of using a catalog. Sell Products (Without Catalog) template⁠ in Ads Manager.
Sell Products: Lifestyle Layout1369752616394017Let people explore your products in action by featuring them in photos. Lookbook template⁠ in Ads Manager.
Sell Products: Grid Layout1932289657009030Use your product catalog to create an experience that lets people shop straight from their mobile device. Storefront template⁠ in Ads Manager.
AR ExperienceThe AR Experience template⁠ is only available via the Ads Manager.

Get element types for a template ​

Step 1. Get the document information for the template ​

Send a GET request to determine which elements are needed for a particular template, Get New Customers in the following example.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/133471657203838?fields=document&access_token=ACCESS-TOKEN"

Example response ​

{
  "document": {
    "name": "Get New Customers",
    "id": "397246414010297"
  },
  "id": "133471657203838"
}

Step 2. Get the element types ​

Use ID for the document field to get specific elements available for a particular template.

curl -i -X GET \
 "https://graph.facebook.com/VERSION/397246414010297?fields=body_elements&access_token=ACCESS-TOKEN"

The list returned shows element types that are available for use in the Get New Customers template.

    {
  "body_elements": [
    {
      "name": "Cover Image or Video",
      "element_type": "PHOTO",
      "id": "397271930674412"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271920674413"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271910674414"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271914007747"
    },
    {
      "name": "Carousel",
      "element_type": "CAROUSEL",
      "id": "397271940674411"
    },
    {
      "name": "Text",
      "element_type": "RICH_TEXT",
      "id": "397271917341080"
    },
    {
      "name": "Button",
      "element_type": "BUTTON",
      "id": "397271924007746"
    }
  ],
  "id": "397246414010297"
}

Publish ​

To publish your Instant Experience ad send a POST request to your Instant Experience ID (CANVAS-ID) and set the is_published field to true.

curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/<CANVAS_ID>

Create an Ad Creative ​

Create an ad creative using the link for an existing Instant Experience (CANVAS-LINK).

curl -X POST \
  -F 'image_hash="<IMAGE_HASH>"' \
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "link_data": {
         "image_hash": "<IMAGE_HASH>",
         "link": "<CANVAS_LINK>",
         "name": "Creative message",
         "call_to_action": {
           "type": "LEARN_MORE"
         }
       }
     }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives

Once the ad creative is ready, you can then go on to create the ad group, ad set, and ad campaign.

Instant Experiences Ads Dialog ​

You can use the Instant Experiences Ads Dialog to provide the Facebook Instant Experiences ad-creation user interfaces in your website. For details about the UI component, see Dialogs.

Set up the Facebook SDK for JavaScript, see:

The JavaScript SDK relies on the logged in user's permissions to create an Instant Experience. If the user does not have the necessary permissions to create an Instant Experience for the supplied page and business, the dialog shows an error. To ensure no errors, the user must be in the business and have 'create ads' permissions for the page.

Then trigger the dialog:

FB.ui({
  display: 'popup',
  method: 'instant_experiences_builder',
  business_id: '<BUSINESS_ID>',
  page_id: '<PAGE_ID>'
}, function(response) {
  // callback
});

You can provide these settings for the plugin:

NameRequiredDescription
displayYesNecessary parameter with set value of popup
methodYesNecessary parameter with set value of instant_experiences_builder
business_idYesYour business ID
page_idYesPage ID you want to associate the Instant Experience with
canvas_idNoID of Instant Experience you want to edit

The parameter canvas_id is optional and is meant to allow a user to edit or preview an existing Instant Experience. If an Instant Experience is complete, you cannot edit it. To preview an Instant Experience, use the Instant Experiences Preview Dialog.

The plugin provides this response on success:

{
  "success": true,
  "id": "CANVAS-ID"
}

The ID returned is a published Instant Experience. You can now use it in ad campaigns. If no response or an undefined response is returned, the viewer closed the dialog before finishing the Instant Experience. The user may have saved the Instant Experiences, but not finished it. You can pull all Instant Experiences that belong to a page using the Graph API to see if there are any unfinished experiences.

Preview an Instant Experience ​

Iframe preview API ​

You can generate a preview an Instant Experience by calling the previews API which returns an iframe, similar to the ad previews API:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v18.0/<CANVAS_ID>/preview

The API returns a response like the following, which you can view by embedding the returned iframe element in HTML:

{
"data": [
    {
      "body": "<iframe src=\"https://www.facebook.com/ads/canvas/preview?d=AQKELApdJxoVp2f3PHl8-pRtYuAh4-_eDupMDbh-pS9zde_EFxckhYQCXu7NYUi4PhhBA7uskIo2Ys3IjIVNGZiS&t=AQKGOPqGI-NWcv1YKbA\" width=\"405\" height=\"720\" scrolling=\"yes\" style=\"border: none;\"></iframe>"
    }
  ],
  "__www_request_id__": "AQnyr47Qp2r5M-ISqSiMgrw"
}

Facebook SDK ​

You can use this dialog to provide a preview of an Instant Experience as someone on Facebook would see it from your website. For details about the UI component, see Dialogs.

Set up the Facebook SDK for JavaScript, see:

The JavaScript SDK relies on the logged in user's permissions to create an Instant Experience. If the user does not have the necessary permissions to view the Instant Experience, the dialog shows an error.

Then trigger the preview dialog:

FB.ui({
  display: 'popup',
  method: 'instant_experiences_preview',
  canvas_id: 'CANVAS-ID'
});

You can provide these settings for the plugin:

NameRequiredDescription
displayYesNecessary parameter with set value of popup
methodYesNecessary parameter with set value of instant_experiences_preview
canvas_idYesID of Instant Experience you want to preview

Create audiences for Instant Experiences ​

To create an engagement audience, an audience of people who have engaged with an Instant Experience, set the object_id parameter of the rule field to the Instant Experience ID (CANVAS-ID) in your POST /act_AD-ACCOUNT/customaudiences call.

People who opened the Instant Experience

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who opened this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_document_open"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

People who clicked any links in the Instant Experience

curl \
  -F 'name=Instant Experience Engagement Audience' \
  -F 'description=People who clicked any links in this Instant Experience' \
  -F 'rule=[{"object_id":"<CANVAS_ID>","event_name":"instant_shopping_element_click"}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

For more information about custom audiences, see Custom Audience, Reference.

Instant Experiences and Instagram Ads ​

Implementing Instant Experiences with Instagram uses the same API calls you use for Instant Experience on Facebook. Note there are limitations when you use Instagram and Instant Experiences:

  • Placements - Available for Instagram Feed and Instagram Stories. If you select Instagram Stories, you should select this as your exclusive ads placement.
  • Instant Experience Elements - Fully supports headers and product sets.

The following Instant Experience elements are partially supported on Instagram:

  • Footer - No swipe to open in clients this renders as Tap to open.
  • Carousel - No photos that link to another Instant Experience; in the client appears as a non-clickable link. For photos and videos, no fit to height, no fit to width or tilt to pan; this renders as fit to width.
  • Button - Cannot link to another Instant Experience or to the App Store.
  • Text - No RTL language support.
  • Video - No 360 videos.
  • Store Locators - Not supported.

Ad Insights ​

See Ad Insights for an overview and descriptions for available metrics.

See also ​

Unofficial mirror for reference/search purposes. All content originates from developers.facebook.com — see the source link at the top of each page. Machine-readable indexes: llms.txt · llms-full.txt · About

Content © Meta Platforms, Inc. · Built by Arjun Aditya