Messenger

  • Click to Messenger ads - Target people and help them discover experiences on Messenger Platform. Select Messenger as a destination under the link_clicks, messages, or conversions objective and use any call-to-action, including Send Message, to Link to Messenger. When people click these, they see an open Messenger thread with a copy of your ad or structured message.
  • Sponsored Messages - Targeted, in-context ads to re-engage people with an existing conversation with your business.

Open Conversations

Drive News Feed ads traffic to a Messenger bot or live chat. Create open threads with customers; people can click CTAs in News Feed ads that open Messenger threads.

Requirements:

  • Supports single image, single video, carousel and slideshow
  • You must set Ad Creative's app_destination field to MESSENGER and provide a welcome in the first open thread
  • You cannot create this ad unit through the Graph API and sponsor with object_story_id.

1. Campaign - Create ads with link_clicks, conversion, or messages objectives:

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.11/act_<AD_ACCOUNT_ID>/campaigns
Reference: Campaign

2. Ad Set - Use any targeting, however only people with Messenger installed see your ad. Supported placements are desktop, mobile feed, and Messenger Home. There is no support for right hand side or audience network placements. There are various optimization_goal and billing_event combinations allowed. To see all permutations, see below.

In this example, billing_event=IMPRESSIONS, optimization_goal=IMPRESSIONS, and a manual bid is set.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Values\BillingEvents;
use FacebookAds\Object\Values\OptimizationGoals;
use FacebookAds\Object\Fields\TargetingSpecsFields;
use FacebookAds\Object\TargetingSpecs;

$adset = new AdSet(null, <AD_ACCOUNT_ID>);
$adset→setData(array(
    AdSetFields::NAME => 'My AdSet',
    AdSetFields::OPTIMIZATION_GOAL => OptimizationGoals::IMPRESSIONS,
    AdSetFields::BILLING_EVENT => BillingEvents::IMPRESSIONS,
    AdSetFields::BID_AMOUNT => 200,
    AdSetFields::DAILY_BUDGET => 100000,
    AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
    AdSetFields::TARGETING => (new TargetingSpecs())→setData(array(
        TargetingSpecsFields::GEO_LOCATIONS => array(
            'countries' => array(
                'US',
            ),
        ),
        TargetingSpecsFields::PAGE_TYPES => array(
            PageTypes::MOBILE_FEED,
        ),
        TargetingSpecsFields::USER_ADCLUSTERS => array(
            array(
                'id' => 6002714885172,
                'name' => 'Cooking',
            ),
            array(
                'id' => 6002714898572,
                'name' => 'Small Business Owners',
            ),
        ),
    )),
));
$adset→create(array(
    AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
curl \
    -F 'name=My AdSet' \
    -F 'optimization_goal=IMPRESSIONS' \
    -F 'billing_event=IMPRESSIONS' \
    -F 'bid_amount=200' \
    -F 'daily_budget=100000' \
    -F 'campaign_id=<CAMPAIGN_ID>' \
    -F 'targeting={ 
      "geo_locations": {"countries":["US"]}, 
      "user_adclusters": [ 
       {"id":6002714885172,"name":"Cooking"}, 
        {"id":6002714898572,"name":"Small Business Owners"} 
      ],
      "page_types": [ 
        "mobilefeed"
      ]  
    }' \
    -F 'status=ACTIVE' \
    -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.6/act_<AD_ACCOUNT_ID>/adsets
Reference: Ad Set

3. Ad Creative -

Set app_destination to MESSENGER. Provide a default welcome message as string in page_welcome_message; this appears when an ad opens in Messenger. Or provide a default template message or a series of up to 5 template messages as Custom JSON Message Blob

To provide a single image ad creative:

curl \
-F 'name=Sample Creative for Messenger' \
-F 'object_story_spec={ 
  "link_data": { 
    "call_to_action": {"type":"LEARN_MORE","value":{"app_destination":"MESSENGER"}}, 
    "description": "Try it out", 
    "image_hash": "<IMAGE_HASH>", 
    "link": "<URL>", 
    "message": "Welcome message", 
  }, 
  "page_id": "<PAGE_ID>" 
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

For video ads:

curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "video_data": { 
      "call_to_action": {
        "type": "LEARN_MORE",
        "value": {
          "app_destination": "MESSENGER",
        }
      },
      "description": "Try it out",
      "image_url": "<THUMBNAIL_URL>", 
      "page_welcome_message": "Welcome message in messenger",
      "video_id": "<VIDEO_ID>"
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

To provide video ad creative with two template replies:

curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "video_data": { 
      "call_to_action": {
        "type": "LEARN_MORE",
        "value": {
          "app_destination": "MESSENGER",
        }
      },
      "description": "Try it out",
      "image_url": "<THUMBNAIL_URL>", 
      "page_welcome_message": "[
      {
        'message': {
          'attachment': {
            'type': 'video',
            'payload': {
              'url': '...',
            }
          }
        }
      },
      {
        'message':
          {
            'text':'Pick a color:',
            'quick_replies':
            [
              {
                'content_type':'text',
                'title':'Red',
                'payload':'Red'
              },
              {
                'content_type':'text',
                'title':'Blue',
                'payload':'Blue'
              }
            ]
          }
      }]",
      "video_id": "<VIDEO_ID>"
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

See Ad Creative, Reference and Message Templates, Reference.

4. Ad - Associate your creative to the ad set:

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.11/act_<AD_ACCOUNT_ID>/ads

See Ad.

Optimization & Billing Options

Below is a table of valid optimization_goal and billing_event combinations for Messenger destination ads. For each combination, automatic and manual bid amount can be set.

optimization_goal billing_event

IMPRESSIONS

IMPRESSIONS

LINK_CLICKS

LINK_CLICKS, IMPRESSIONS

REPLIES

IMPRESSIONS

More details on valid optimization_goal and billing_event combinations for ads can be found here.

Send Sponsored Messages to people communicating with your business on Messenger with an Open Thread Custom Audience or a Page Scoped ID Custom Audience.

Requirements

1. Campaign - Create a campaign with LINK_CLICKS or CONVERSIONS as objectives only.

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.11/act_<AD_ACCOUNT_ID>/campaigns

See Reference: Campaign

2. Ad Set

An Open Thread CA lists anyone who started messages with your business through any Messenger thread. To create one:

curl \
-F 'name=open_thread_audience' \
-F 'subtype=ENGAGEMENT' \
-F 'retention_days=90' \
-F 'prefill=1' \
-F 'rule=[{"page_messaged":<PAGE_ID>}]' \
-F 'access_token=<ACCESS_TOKEN>' \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/customaudiences"

These restrictions apply to Sponsored Message Ad Sets:

  • You must target either a Messenger Open Thread Custom Audience or Page Scoped ID CA. Audience must be at least 50 people in size. You can additionally include other targeting, such as demographics, geographics, or interests. You can also use flexible targeting to combine your Open thread CA with existing Custom Audiences.
  • Specify messenger as a publisher_platforms in targeting. Mixed placements prohibited; target messenger only.
  • CPM with billing_event=IMPRESSIONS, optimization_goal=IMPRESSIONS only. Minimum bid varies per country, see minimum bids.
  • You must specify the page in promoted_object.

Create an ad set with an Open Threads Custom Audience and an existing Custom Audience:

curl \
-F 'name=Sponsored Messages Ad Set' \
-F 'optimization_goal=IMPRESSIONS' \
-F 'billing_event=IMPRESSIONS' \
-F 'bid_amount=2400' \
-F 'daily_budget=10000' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting=
 {"geo_locations":{"countries":["US"]}, 
  "publisher_platforms":["messenger"], 
  "device_platforms":["mobile"],
  "flexible_spec":[{"custom_audiences":[{"id":<OPEN_THREAD_CA>}]},{"custom_audiences":[{"id":<CUSTOM_AUDIENCE_ID>}]}]}' \
-F 'status=PAUSED' \
-F 'promoted_object={"page_id":<PAGE_ID>}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

See Ad Set, Reference and Placements, Reference

3. Ad Creative

Only link_data supported. For send message capability use MESSAGE_PAGE as the CTA for API. In such case, link is a required field inside the link_data while the destination is still set as Messenger.

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

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'Message above the ad',
  AdCreativeLinkDataFields::NAME => 'Title of the Ad',
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::DESCRIPTION => 'Subtext below the title',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::SHOP_NOW,
    'value' => array(
      'link' => '<URL>',
    ),
  ),
));

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

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'Message above the ad'
link_data[AdCreativeLinkData.Field.link] = '<URL>'
link_data[AdCreativeLinkData.Field.caption] = 'www.domain.com'
link_data[AdCreativeLinkData.Field.name] = 'Title of the ad'
link_data[AdCreativeLinkData.Field.description] = 'Subtext below the title'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'

call_to_action = {
    'type': 'SIGN_UP',
    'value': {
        'link': '<URL>',
    },
}

link_data[AdCreativeLinkData.Field.call_to_action] = call_to_action

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'AdCreative for Link Ad with CTA'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()
print(creative)
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "link_data": { 
      "call_to_action": {"type":"SHOP_NOW","value":{"link":"<URL>"}}, 
      "description": "Subtext below the title", 
      "image_hash": "<IMAGE_HASH>", 
      "link": "<URL>", 
      "message": "Message above the ad", 
      "name": "Title of the Ad" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

See Ad Creative, Reference.

4. Ad - Associate your creative to the ad set:

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.11/act_<AD_ACCOUNT_ID>/ads

See Ad, Reference

Reporting

  • For Sponsored Message, Facebook reports the number of clicks and replies. Note that number of clicks are reported as link_click.

  • For Open Conversations in Messenger, Facebook reports the number of impressions, reach, and clicks. The number of clicks are reported as link_click.

To attribute a Page Scoped ID back to the ad ID, you should query for metadata. ad_id appears in metadata for the thread's message:

{
  "sender":{
    "id":"PAGE_ID"
  },
  "recipient":{
    "id":"USER_ID"
  },
  "timestamp":1457764197627,
  "message":{
    "is_echo":true,
    "app_id":1517776481860111,
    "metadata": "{\"ad_id\":\"12345\"}",
    "mid":"mid.1457764197618:41d102a3e1ae206a38",
    "seq":73,
    ...
  }
}