Messenger

Ads that click to Messenger

Start conversations in Messenger with ads placed in Facebook News Feed, Instagram, or Messenger Inbox to a Messenger bot or live chat.

Requirements

• Supports single image, single video, carousel, and slideshow.
• You must set the 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.

Step 1: Create a Campaign

Create ads with messages or conversion objective. The Messages objective optimizes delivery of ads to people more likely to respond to your business in Messenger and should be used for most click to Messenger campaigns. The Conversions objective should be used by advertisers if they're tracking events with a Facebook pixel and driving conversion events at scale.

curl -X POST \
  -F 'name="My campaign"' \
  -F 'objective="LINK_CLICKS"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v9.0/act_<AD_ACCOUNT_ID>/campaigns

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Campaign = bizSdk.Campaign;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My campaign',
  'objective' : 'LINK_CLICKS',
  'status' : 'PAUSED',
  'special_ad_categories' : [],
};
const campaigns = (new AdAccount(id)).createCampaign(
  fields,
  params
);
logApiCallResult('campaigns api call complete.', campaigns);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My campaign',
  'objective' => 'LINK_CLICKS',
  'status' => 'PAUSED',
  'special_ad_categories' => array(),
);
echo json_encode((new AdAccount($id))->createCampaign(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.campaign import Campaign
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My campaign',
  'objective': 'LINK_CLICKS',
  'status': 'PAUSED',
  'special_ad_categories': [],
}
print AdAccount(id).create_campaign(
  fields=fields,
  params=params,
)

import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCampaign()
      .setName(\"My campaign\")
      .setObjective(Campaign.EnumObjective.VALUE_LINK_CLICKS)
      .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
      .setParam(\"special_ad_categories\", \"[]\")
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
campaigns = ad_account.campaigns.create({
    name: 'My campaign',
    objective: 'LINK_CLICKS',
    status: 'PAUSED',
    special_ad_categories: [],
})

Step 2: Create 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 CONVERSATIONS and billing_event combinations you can use. See Valid Optimizations below.

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"} 
      ],
      "device_platforms ": [ 
        "mobile "
      ]  
    }' \
    -F 'status=ACTIVE' \
    -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/adsets

Step 3: Create 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"}}, 
    "image_hash": "<IMAGE_HASH>", 
    "link": "<URL>", 
    "message": "Welcome message", 
  }, 
  "page_id": "<PAGE_ID>" 
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/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",
        }
      },
      "link_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",
        }
      },
      "link_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.

Step 4: Associate your creative to the ad set

curl -X POST \
  -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/v9.0/act_<AD_ACCOUNT_ID>/ads

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)

import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})

For more details, see Ad.

Optimization & Billing Options

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

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

Sponsored Messages

Sponsored messages are a type of ad that can be sent directly as a message to people that have an open conversation with your business in Messenger.

Step 1: 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/<VERSION>/act_<AD_ACCOUNT_ID>/campaigns

See Reference: Campaign

Step 2: Create 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 a 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/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

See Ad Set, Reference and Placements, Reference.

Step 3: Create 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/<API_VERSION>/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/<VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

See Ad Creative, Reference.

Step 4: 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/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads

See Ad, Reference.