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.

Sponsored messages are a type of ad that is sent directly as a message to everyone who currently has an open chat with your Facebook Page.

1. Campaign - Create a campaign with MESSAGES objective

curl \
-F 'name=My campaign' \
-F 'objective=MESSAGES' \
-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

These restrictions apply to Sponsored Message Ad Sets:

  • Your sponsored message will be eligible to be served to any person who has opened a thread with your page. You can additionally include other targeting, such as demographics, geographics, custom audiences or interests.
  • CPM with billing_event=IMPRESSIONS, optimization_goal=IMPRESSIONS only. Minimum bid varies per country, see minimum bids.
  • Specify messenger as a publisher_platforms in targeting. Note: Mixed placements are not allowed with Sponsored Message and you must target only Messenger.
  • Specify sponsored_messages as a messenger_positions in targeting.
  • device_platforms must be both mobile and desktop
  • You must specify the page in promoted_object.

Create an new ad set:

curl \
-F 'name=Sponsored Messages Ad Set' \
-F 'optimization_goal=IMPRESSIONS' \
-F 'billing_event=IMPRESSIONS' \
-F 'bid_amount=2500' \
-F 'daily_budget=10000' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting=
 {"publisher_platforms":["messenger"],
  "messenger_positions":["sponsored_messages"],
  "device_platforms":["mobile", "desktop"]}' \
-F 'status=PAUSED' \
-F 'promoted_object={"page_id":<PAGE_ID>}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<v2.11/act_<AD_ACCOUNT_ID>/adsets

NOTE: It is not necessary to specify a custom audience (Open Threads or otherwise).

See Ad Set, Reference and Placements, Reference

3. Ad Creative

  • In the Ad Creative, you need to specify the message which user will recieve in messenger_sponsored_message field. The format of the message is same as used by Messenger Platform
  • Currently, Sponsored Messages support only Text or Images with buttons or quick replies. Note: You must specify payload or URL with the button
curl \
-F 'object_id=<PAGE_ID>' \
-F 'object_type=SHARE' \
-F 'messenger_sponsored_message={"message":{"text":"Sample Text", "quick_replies":[{"title":"Quick Reply Text", "content_type":"text"}]}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives
curl \
-F 'object_id=<PAGE_ID>' \
-F 'object_type=SHARE' \
-F 'messenger_sponsored_message={"message":{"attachment":{"type":"template", "payload":{"template_type":"generic", "elements":[{"title":"Image Text", "buttons":[{"type":"web_url", "title":"button text", "url":"<URL>"}], "image_hash":"<IMAGE_HASH>"}]}},"text":"Ad text"}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

See Ad Creative, Reference.

4. Ad - Final step is to create the ad using the creative you created in Step 3.

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