Canvas Ads

You can easily create Canvas campaigns on Facebook and Instagram through the API. By using sight, sound, and motion, the video format allows advertisers to effectively drive both brand and direct response objectives.

For Instagram, this API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API with Instagram. For details and limitations see Instagram and Canvas Ads

A canvas ad has these elements:

  • Header and Footer
  • Carousel
  • Button and Text
  • Photo
  • Video
  • Product set
  • Store Locator

In these examples we show how you can create each element and how they're used to create a canvas. See Clicks to Website: Canvas on Facebook Ads guide for a visual example on each element.

Managing Canvas Ads

To create an ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_POST,
  $params)->getContent();
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/v2.10/<PAGE_ID>/canvases

To read an ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "body_elements", 
    "canvas_link", 
    "id", 
    "is_hidden", 
    "is_published", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ID>

Note, you can only update an unpublished canvas. To update it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'background_color' => 'FFFFFF',
  'body_element_ids' => array(<CANVAS_PHOTO_ID>),
  'is_hidden' => false,
  'is_published' => false,
  'name' => 'Canvas Name',
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
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/v2.10/<CANVAS_ID>

Publishing

To publish your ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'is_published' => true,
);

$data = Api::instance()->call(
  '/' . <CANVAS_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'is_published=1' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ID>

If you want to preview your ad before you publish it, you can trigger a notification sent to your phone:

curl \
-F 'user_ids=[USER_ID]' \
-F 'access_token=ACCESS_TOKEN' \
https://graph.facebook.com/VERSION/CANVAS_ID/preview_notifications

Get Page Canvases

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'background_color',
    'body_elements',
    'canvas_link',
    'id',
    'is_hidden',
    'is_published',
    'last_editor',
    'name',
    'owner',
    'update_time',
  ),
);

$data = Api::instance()->call(
  '/' . <PAGE_ID> . '/canvases',
  RequestInterface::METHOD_GET,
  $params)->getContent();
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/v2.10/<PAGE_ID>/canvases

To create a header for your ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_header' => array(
    'name' => 'Canvas Header Name',
    'background_color' => 'FFFFFF',
    'child_elements' => array(<CANVAS_PHOTO_ID>),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_header={ 
    "name": "Canvas Header Name", 
    "background_color": "FFFFFF", 
    "child_elements": ["<CANVAS_PHOTO_ID>"] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read an existing header:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'child_elements',
    'id',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_HEADER_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "child_elements", 
    "id", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_HEADER_ID>

To update a header:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'name' => 'Canvas Header Name',
  'background_color' => 'FFFFFF',
  'child_elements' => array(<CANVAS_PHOTO_ID>),
);

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_HEADER_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'name=Canvas Header Name' \
  -F 'background_color=FFFFFF' \
  -F 'child_elements=["<CANVAS_PHOTO_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_HEADER_ID>

If you want to delete a header:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

To create one:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_footer' => array(
    'name' => 'Canvas Footer Name',
    'child_elements' => array(<CANVAS_BUTTON_ID>),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_footer={"name":"Canvas Footer Name","child_elements":["<CANVAS_BUTTON_ID>"]}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read an existing footer:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'child_elements',
    'id',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_FOOTER_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "child_elements", 
    "id", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_FOOTER_ID>

To update a footer:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'name' => 'Canvas Footer Name',
  'child_elements' => array(<CANVAS_BUTTON_ID>),
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_FOOTER_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'name=Canvas Footer Name' \
  -F 'child_elements=["<CANVAS_BUTTON_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_FOOTER_ID>

To delete a footer:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

To create a carousel:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_carousel' => array(
    'bottom_padding' => 12,
    'child_elements' => array(
      <CANVAS_PHOTO_ID_1>,
      <CANVAS_PHOTO_ID_2>,
      <CANVAS_PHOTO_ID_3>,
    ),
    'name' => 'Canvas Carousel Name',
    'style' => 'FIT_TO_WIDTH',
    'top_padding' => 12,
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_carousel={ 
    "bottom_padding": 12, 
    "child_elements": [ 
      "<CANVAS_PHOTO_ID_1>", 
      "<CANVAS_PHOTO_ID_2>", 
      "<CANVAS_PHOTO_ID_3>" 
    ], 
    "name": "Canvas Carousel Name", 
    "style": "FIT_TO_WIDTH", 
    "top_padding": 12 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'child_elements',
    'id',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_CAROUSEL_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "child_elements", 
    "id", 
    "name" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_CAROUSEL_ID>

To update it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'bottom_padding' => 12,
  'child_elements' => array(
    <CANVAS_PHOTO_ID_1>,
    <CANVAS_PHOTO_ID_2>,
    <CANVAS_PHOTO_ID_3>,
  ),
  'name' => 'Canvas Carousel Name',
  'style' => 'FIT_TO_WIDTH',
  'top_padding' => 12,
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_CAROUSEL_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'bottom_padding=12' \
  -F 'child_elements=[ 
    "<CANVAS_PHOTO_ID_1>", 
    "<CANVAS_PHOTO_ID_2>", 
    "<CANVAS_PHOTO_ID_3>" 
  ]' \
  -F 'name=Canvas Carousel Name' \
  -F 'style=FIT_TO_WIDTH' \
  -F 'top_padding=12' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_CAROUSEL_ID>

To delete it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Here are options you can use for a carousel in Canvas Ads:

Name Required or Optional Description

style

Optional

FIT_TO_WIDTH or FIT_TO_HEIGHT

Buttons

To create:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_button' => array(
    'bottom_padding' => 0,
    'button_color' => 'FF000000',
    'button_style' => 'BUTTON_FILLED',
    'font_family' => 'sans-serif',
    'font_size' => 15,
    'line_height' => 1,
    'name' => 'Canvas Button Name',
    'open_url_action' => array('url' => '<URL>'),
    'rich_text' => array('plain_text' => 'Click Me'),
    'text_alignment' => 'CENTER',
    'text_color' => 'FF777777',
    'top_padding' => 0,
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_button={ 
    "bottom_padding": 0, 
    "button_color": "FF000000", 
    "button_style": "BUTTON_FILLED", 
    "font_family": "sans-serif", 
    "font_size": 15, 
    "line_height": 1, 
    "name": "Canvas Button Name", 
    "open_url_action": {"url":"<URL>"}, 
    "rich_text": {"plain_text":"Click Me"}, 
    "text_alignment": "CENTER", 
    "text_color": "FF777777", 
    "top_padding": 0 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'action',
    'id',
    'name',
    'rich_text',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_BUTTON_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "action", 
    "id", 
    "name", 
    "rich_text" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_BUTTON_ID>

To update a button:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'bottom_padding' => 0,
  'button_color' => 'FF000000',
  'button_style' => 'BUTTON_FILLED',
  'font_family' => 'sans-serif',
  'font_size' => 15,
  'line_height' => 1,
  'name' => 'Canvas Button Name',
  'open_url_action' => array('url' => '<URL>'),
  'rich_text' => array('plain_text' => 'Click Me'),
  'text_alignment' => 'CENTER',
  'text_color' => 'FF777777',
  'top_padding' => 0,
);

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_BUTTON_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'bottom_padding=0' \
  -F 'button_color=FF000000' \
  -F 'button_style=BUTTON_FILLED' \
  -F 'font_family=sans-serif' \
  -F 'font_size=15' \
  -F 'line_height=1' \
  -F 'name=Canvas Button Name' \
  -F 'open_url_action={"url":"<URL>"}' \
  -F 'rich_text={"plain_text":"Click Me"}' \
  -F 'text_alignment=CENTER' \
  -F 'text_color=FF777777' \
  -F 'top_padding=0' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_BUTTON_ID>

To delete a button:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Here are options you can use for buttons:

Name Required or Optional Description

button_style

Required

BUTTON_OUTLINE, BUTTON_FILLED

Text

To create text:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_text' => array(
    'name' => 'Canvas Text Name',
      'rich_text' => array(
        'plain_text' => 'Canvas Text',
        'inline_styles' => array(
          array('offset' => 10, 'length' => 9, 'style' => 'underline'),
          array('offset' => 20, 'length' => 9, "style" => 'bold'),
       ),
     ),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_text={ 
    "name": "Canvas Text Name", 
    "rich_text": { 
      "plain_text": "Canvas Text", 
      "inline_styles": [ 
        { 
          "offset": 10, 
          "length": 9, 
          "style": "underline" 
        }, 
        { 
          "offset": 20, 
          "length": 9, 
          "style": "bold" 
        } 
      ] 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read text:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'id',
    'name',
    'rich_text',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_TEXT_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "id", 
    "name", 
    "rich_text" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_TEXT_ID>

To update existing text:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'name' => 'Canvas Text Name',
    'rich_text' => array(
      'plain_text' => 'Canvas Text',
      'inline_styles' => array(
        array('offset' => 10, 'length' => 9, 'style' => 'underline'),
        array('offset' => 20, 'length' => 9, "style" => 'bold'),
     ),
   ),
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_TEXT_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'name=Canvas Text Name' \
  -F 'rich_text={ 
    "plain_text": "Canvas Text", 
    "inline_styles": [ 
      { 
        "offset": 10, 
        "length": 9, 
        "style": "underline" 
      }, 
      { 
        "offset": 20, 
        "length": 9, 
        "style": "bold" 
      } 
    ] 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_TEXT_ID>

To delete text:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Photos

You should provide a PHOTO_ID for a photo uploaded to a Facebook Page.

To create a photo:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_photo' => array(
    'bottom_padding' => 20,
    'name' => 'Canvas Photo Name',
    'open_url_action' => array('url' => '<URL>'),
    'photo_id' => <PHOTO_ID>,
    'style' => 'FIT_TO_WIDTH',
    'top_padding' => 20,
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_photo={ 
    "bottom_padding": 20, 
    "name": "Canvas Photo Name", 
    "open_url_action": {"url":"<URL>"}, 
    "photo_id": "<PHOTO_ID>", 
    "style": "FIT_TO_WIDTH", 
    "top_padding": 20 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read one:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'action',
    'id',
    'name',
    'photo',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_PHOTO_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "action", 
    "id", 
    "name", 
    "photo" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_PHOTO_ID>

To update a photo:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'bottom_padding' => 20,
  'name' => 'Canvas Photo Name',
  'open_url_action' => array('url' => '<URL>'),
  'photo_id' => <PHOTO_ID>,
  'top_padding' => 20,
);

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_PHOTO_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'bottom_padding=20' \
  -F 'name=Canvas Photo Name' \
  -F 'open_url_action={"url":"<URL>"}' \
  -F 'photo_id=<PHOTO_ID>' \
  -F 'top_padding=20' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_PHOTO_ID>

To delete a photo:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Options for photos include:

Name Required or Optional Description

style

Optional

FIT_TO_WIDTH, FIT_TO_WIDTH_EXPANDABLE, FIT_TO_HEIGHT

Using Photos with Product Tags

Create an ads experience that mimics browsing a printed, lifestyle catalog featuring desired products to promote. You can tag featured products in the image and a tag appears on the image.

This API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API.

When someone taps the tag, a thumbnail for that product appears in a rotating group of thumbnails, including all tagged products. Someone can tap the thumbnail to be taken to the product's product detail page. This uses the canvas photo with product tags element API. For example:

curl 
  -F 'canvas_photo={ 
    "bottom_padding": 20, 
    "name": "Canvas Photo Name", 
    "open_url_action": {"url":"URL"}, 
    "photo_id": "PHOTO_ID", 
    "style": "FIT_TO_WIDTH", 
    "top_padding": 20,
    "product_tags": "[{product_id: PRODUCT_ID, coordinates: [0.65, 0.58]}, {product_id: PRODUCT_ID}]" 
  }' 
  }' 
  -F 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/PAGE_ID/canvas_elements

The options available for product tags are:

Field Name Description Type Required

product_tags

Provide a list of products for the photo

array

Yes

product_id

Product id for tapped photo

number

Yes

coordinates

Spot coordinates on the photo.

array, where x and y greater than zero and less than 1

No. If none specified, there is no spot on the photo

To read this:

curl -G 
  --data-urlencode 'fields=[ 
    "action", 
    "id", 
    "name", 
    "photo",
    "product_tags"
  ]' 
  -d 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/CANVAS_PHOTO_ID

And to update it:

curl \
  -F 'bottom_padding=20' \
  -F 'name=Canvas Photo Name' \
  -F 'open_url_action={"url":"URL"}' \
  -F 'photo_id=PHOTO_ID' \
  -F 'top_padding=20' \
  -F 'product_tags=[{product_id: PRODUCT_ID, coordinates: [0.65, 0.58]}, {product_id: PRODUCT_ID}]' \
  -F 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/CANVAS_ELEMENT_PHOTO_ID

If you want delete your tag:

curl -X DELETE 
  -d 'access_token=ACCESS_TOKEN' 
  https://graph.facebook.com/VERSION/CANVAS_ELEMENT_ID

Videos

You should provide a VIDEO_ID which refers to a video uploaded to a page.

To create a Canvas ad with a video:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_video' => array(
    'bottom_padding' => 24,
    'name' => 'Canvas Video Name',
    'style' => 'FIT_TO_WIDTH',
    'top_padding' => 24,
    'video_id' => <VIDEO_ID>,
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_video={ 
    "bottom_padding": 24, 
    "name": "Canvas Video Name", 
    "style": "FIT_TO_WIDTH", 
    "top_padding": 24, 
    "video_id": "<VIDEO_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

Options for videos include:

Name Required or Optional Description

style

Optional

FIT_TO_WIDTH, FIT_TO_HEIGHT

To read a Canvas video ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'id',
    'name',
    'video',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_VIDEO_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "id", 
    "name", 
    "video" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_VIDEO_ID>

To update one:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'bottom_padding' => 20,
  'name' => 'Canvas Video Name',
  'style' => 'FIT_TO_WIDTH',
  'top_padding' => 20,
  'video_id' => <VIDEO_ID>,
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_VIDEO_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'bottom_padding=20' \
  -F 'name=Canvas Video Name' \
  -F 'style=FIT_TO_WIDTH' \
  -F 'top_padding=20' \
  -F 'video_id=<VIDEO_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_VIDEO_ID>

To delete one:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Product Sets

Display products from a Dynamic Ads product catalog. For example:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_product_set' => array(
    'bottom_padding' => 8,
    'max_items' => 6,
    'name' => 'Canvas Product Set Name',
    'product_set_id' => <PRODUCT_SET_ID>,
    'top_padding' => 24,
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_product_set={ 
    "bottom_padding": 8, 
    "max_items": 6, 
    "name": "Canvas Product Set Name", 
    "product_set_id": "<PRODUCT_SET_ID>", 
    "top_padding": 24 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read one:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'id',
    'name',
    'product_set_id',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_PRODUCT_SET_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  --data-urlencode 'fields=[ 
    "id", 
    "name", 
    "product_set_id" 
  ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_PRODUCT_SET_ID>

To update the ad:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'bottom_padding' => 8,
  'max_items' => 6,
  'name' => 'Canvas Product Set Name',
  'product_set_id' => <PRODUCT_SET_ID>,
  'top_padding' => 24,
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_PRODUCT_SET_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'bottom_padding=8' \
  -F 'max_items=6' \
  -F 'name=Canvas Product Set Name' \
  -F 'product_set_id=<PRODUCT_SET_ID>' \
  -F 'top_padding=24' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_PRODUCT_SET_ID>

To delete it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Product Lists

Select a product catalog and then manually provide the product ID, name and color variations to promote in a collection's ad creative. Use this option if you or your advertiser does not want to set-up a product set from a catalog feed. This option makes creating of ads from product catalog simpler. Note that we do not save selected products as a product set for later reuse.

This API is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use this API.

Use this option to select which item colors you want to show in an ad and control the order products appear. Because this is a manual ordering, we do not dynamically rank or display products based on popularity or relevancy to each viewer.

Only E-commerce and travel hotel vertical catalogs are currently supported.

To create a product list:

curl \
  -F 'canvas_product_list={ 
    "bottom_padding": 20, 
    "name": "Canvas Product List Name", 
    "product_id_list": "[product_id_1, product_id_2, product_id_3, product_id_4]",
    "item_headline": "See more at {{product.brand | titleize}}",
    "item_description": "{{product.price}}",
    "top_padding": 20 
  }' \
  -F 'access_token=TOKEN' \
  https://graph.facebook.com/VERSION/PAGE_ID/canvas_elements
  

To read one:

curl -G \--data-urlencode 'fields=[
"name",
"product_id_list"
]' \-d 'access_token=TOKEN' \
https://graph.facebook.com/VERSION/PRODUCT_LIST_ELEMENT_ID
  

To update one:

curl \
  -F 'bottom_padding=8' \
  -F 'name=Canvas Product List Name' \
  -F 'product_id_list=[product_id_1, product_id_2, product_id_3, product_id_4]' \
  -F 'item_headline=See more at {{product.url}}' \
  -F 'item_description={{product.current_price}}' \
  -F 'top_padding=24' \
  -F 'access_token=TOKEN' \
  https://graph.facebook.com/VERSION/CANVAS_ELEMENT_PRODUCT_LIST_ID
  

To delete it:

curl -X DELETE \
  -d 'access_token=TOKEN' \
  https://graph.facebook.com/VERSION/CANVAS_ELEMENT_ID
  

The options available for product lists are:

Field NameDescriptionTypeRequired

product_id_list

Provide a list of products for the element

array

Yes. Must be more than four IDs. IDs must be from Dynamic Ads product catalog or Dynamic Ads for Travel, hotel catalog

Canvas Store Locator

Provide a store locator in your Canvas Ad. For example:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'canvas_store_locator' => array(
    'header_background_color' => 'FF000000',
    'name' => 'Canvas Store Locator Name',
    'page_set_id' => <PLACE_PAGE_SET_ID>,
    'typeface' => 'HelveticaNeue-Light',
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/canvas_elements',
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'canvas_store_locator={ 
    "header_background_color": "FF000000", 
    "name": "Canvas Store Locator Name", 
    "page_set_id": "<PLACE_PAGE_SET_ID>", 
    "typeface": "HelveticaNeue-Light" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<PAGE_ID>/canvas_elements

To read it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'fields' => array(
    'id',
    'name',
  ),
);

$data = Api::instance()->call(
  '/' . <CANVAS_STORE_LOCATOR_ID>,
  RequestInterface::METHOD_GET,
  $params)->getContent();
curl -G \
  -d 'fields=["id","name"]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_STORE_LOCATOR_ID>

To change it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'header_background_color' => 'FF000000',
  'name' => 'Canvas Store Locator Name',
  'page_set_id' => <PLACE_PAGE_SET_ID>,
  'typeface' => 'HelveticaNeue-Light',
);

$data = Api::instance()->call(
  '/'.<CANVAS_ELEMENT_STORE_LOCATOR_ID>,
  RequestInterface::METHOD_POST,
  $params)->getContent();
curl \
  -F 'header_background_color=FF000000' \
  -F 'name=Canvas Store Locator Name' \
  -F 'page_set_id=<PLACE_PAGE_SET_ID>' \
  -F 'typeface=HelveticaNeue-Light' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_STORE_LOCATOR_ID>

To delete it:

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$data = Api::instance()->call(
  '/' . <CANVAS_ELEMENT_ID>,
  RequestInterface::METHOD_DELETE,
  array())->getContent();
curl -X DELETE \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/<CANVAS_ELEMENT_ID>

Creating Canvas Ads

In this example we create a canvas ad using an existing canvas ID. First we provide ad creative for the Canvas ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::LINK => '<CANVAS_LINK>',
  AdCreativeLinkDataFields::NAME => 'Creative message',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::LEARN_MORE,
  ),
));

$story = new AdCreativeObjectStorySpec();
$story->setData(array(
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeFields::OBJECT_STORY_SPEC => $story,
));

$creative->create();
curl \
  -F 'image_hash=<IMAGE_HASH>' \
  -F 'object_story_spec={ 
    "link_data": { 
      "call_to_action": {"type":"LEARN_MORE"}, 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<CANVAS_LINK>", 
      "name": "Creative message" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Then we create an ad:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>,
}
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setStatus(Ad.EnumStatus.VALUE_PAUSED)
  .execute();
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/ads

We creat an ad set:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Targeting;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My Ad Set',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
  )),
));
$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet
from facebookads.adobjects.targeting import Targeting

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')

params = {
    AdSet.Field.name: 'My Ad Set',
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.daily_budget: 1000,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.bid_amount: 2,
    AdSet.Field.targeting: {
        Targeting.Field.geo_locations: {
            'countries': ['US'],
        },
    },
    AdSet.Field.status: AdSet.Status.active,
}
adset = ad_account.create_ad_set(params=params)
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My Ad Set")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
  )
  .setStatus(AdSet.EnumStatus.VALUE_PAUSED)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My Ad Set' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adsets

Finally we create a campaign:

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;
use FacebookAds\Object\Values\CampaignObjectiveValues;

$campaign = new Campaign(null, 'act_<AD_ACCOUNT_ID>');
$campaign->setData(array(
  CampaignFields::NAME => 'My campaign',
  CampaignFields::OBJECTIVE => CampaignObjectiveValues::LINK_CLICKS,
));

$campaign->create(array(
  Campaign::STATUS_PARAM_NAME => Campaign::STATUS_PAUSED,
));
from facebookads.adobjects.campaign import Campaign

campaign = Campaign(parent_id='act_<AD_ACCOUNT_ID>')
campaign.update({
    Campaign.Field.name: 'My Campaign',
    Campaign.Field.objective: Campaign.Objective.link_clicks,
})

campaign.remote_create(params={
    'status': Campaign.Status.paused,
})
Campaign campaign = new AdAccount(act_<AD_ACCOUNT_ID>, context).createCampaign()
  .setName("My campaign")
  .setObjective(Campaign.EnumObjective.VALUE_LINK_CLICKS)
  .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
  .execute();
String campaign_id = campaign.getId();
curl \
  -F 'name=My campaign' \
  -F 'objective=LINK_CLICKS' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/campaigns

Using Canvas Templates

You can use a template as quick way to create a Canvas 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.

Facebook has five Canvas templates in our ads tools: "Get New Customers", "Showcase Your Business", "Sell Products", "Sell Products, Lifestyle Layout", and "Sell Products, Grid". See these examples to retrieve template contents via the API. You can use this to construct templates in your own tools.

First get the body elements, for example, get them from a "Get New Customers" template:

curl -G \
  --data-urlencode 'fields=[  
    "name", 
    "body_elements",
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/TEMPLATE_ID

Returns:

{
 "name": "Get New Customers", 
"body_elements": [
 {
 "name": "Cover Image or Video", "element_type": "PHOTO", "id": "ELEMENT_ID" }, 
{
 "name": "Text", "element_type": "RICH_TEXT", "id": "ELEMENT_ID" 
}, {
 "name": "Text", "element_type": "RICH_TEXT", "id": "ELEMENT_ID" 
}, {
 "name": "Button", "element_type": "BUTTON", "id": "ELEMENT_ID" 
}, {
 "name": "Carousel", "element_type": "CAROUSEL", "id": "ELEMENT_ID" 
}
....
], 
"id": "TEMPLATE_ID",
}

Now you can then get element content, for example you can get a photo element:

curl -G \
  --data-urlencode 'fields=[ 
    "action", 
    "name", 
    "photo" 
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/ELEMENT_ID 

To retrieve a RICH_TEXT element:

curl -G \
  --data-urlencode 'fields=[
    "name", 
    "rich_text" 
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/ELEMENT_ID 

To retrieve a CAROUSEL element:

curl -G \
  --data-urlencode 'fields=[ 
    "name", 
    "child_elements",
    "style" 
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/ELEMENT_ID

To get a button element:

curl -G \
  --data-urlencode 'fields=[  
    "name", 
    "action", 
    "rich_text",
    "text_alignment",
    "text_color",
    "font_size",
    "button_color",
    "button_style",
    "background_color",
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/ELEMENT_ID

Template Examples

Here are additional examples that demonstrate how you can retrieve template content. To get body elements for "Showcase Your Business":

curl -G \
  --data-urlencode 'fields=[  
    "name", 
    "body_elements",
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/TEMPLATE_ID

This returns all elements:

{
 "name": "Showcase Your Business", 
"body_elements": [
 {
 "name": "Cover Image or Video", "element_type": "VIDEO", "id": "ELEMENT_ID" }, {
 "name": "Text", "element_type": "RICH_TEXT", "id": "ELEMENT_ID"
 }, {
 "name": "Image or Video", "element_type": "PHOTO", "id": "ELEMENT_ID" 
}, {
 "name": "Carousel", "element_type": "CAROUSEL", "id": "ELEMENT_ID" 
}, {
 "name": "Text", "element_type": "RICH_TEXT", "id": "ELEMENT_ID" 
}, {
 "name": "Image or Video", "element_type": "PHOTO", "id": "ELEMENT_ID" 
}, {
 "name": "Button", "element_type": "BUTTON", "id": "ELEMENT_ID" 
} 
], "id": "ELEMENT_ID"
}

Now you can get content for a specific element, such as the video:

curl -G \
  --data-urlencode 'fields=[ 
    "name", 
    "video" 
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/ELEMENT_ID

To get body elements for a "Sell Products" template:

curl -G \
  --data-urlencode 'fields=[  
    "name", 
    "body_elements",
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/TEMPLATE_ID

This returns:

{
 "name": "Sell Products", 
"body_elements": [
 {
 "name": "Cover Image or Video", "element_type": "PHOTO", "id": "1867119740170572 (https://developers.facebook.com/tools/explorer/ELEMENT_ID" }, {
 "name": "Text", "element_type": "RICH_TEXT", "id": "ELEMENT_ID" 
}, ....
], 
"id": "TEMPLATE_ID", 
}

To get body elements for a "Sell Products, Lifestyle" template:

curl -G \
  --data-urlencode 'fields=[  
    "name", 
    "body_elements",
  ]' \
  -d 'access_token=ACCESS_TOKEN' \
  https://graph.facebook.com/VERSION/TEMPLATE_ID

Results:

{
 "name": "Sell Products", 
"body_elements": [
 {
 "name": "Cover Image or Video", "element_type": "VIDEO", "id": "ELEMENT_ID" }, {
 "name": "Headline", "element_type": "RICH_TEXT", "id": "ELEMENT_ID" 
}, 
....
], 
"id": "TEMPLATE ID"
}

Once you have element IDs for your template, you can get content for the element. For example, to get content for a photo element, including product tags:

curl -G \
--data-urlencode 'fields=[
"name",
"action",
"photo" ,
"product_tags"
]' \
-d 'access_token=ACCESS_TOKEN' \
https://graph.facebook.com/VERSION/ELEMENT_ID

Engagement Audiences for Canvas

Automatically create audiences for people who engaged with Canvas, this is known as an engagement audience.

Create a Canvas engagement audience by creating a Custom Audience with subtype set to ENGAGEMENT, object_id to the <CANVAS_ID>, and the rule to track one of the following Canvas events:

People who opened the Canvas

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

People who clicked any links in the Canvas

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

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

Canvas and Instagram Ads

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

  • Placements - Available for Instagram Stories only and you should select this as your exclusive ads placement.
  • Canvas Elements - Fully supports Canvas Headers only

We partially support these Canvas Elements on Instagram:

  • Footer - No swipe to open in clients this renders as Tap to open.
  • Carousel - No photos that link to another canvas; 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 canvas or to the App Store.
  • Text - No RTL language support.
  • Video - No 360 videos.
  • Product Sets from Dynamic Ads, Store Locators - Not supported.

Ad Insights

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