Sending Sponsored Messages with the Messenger Platform

Graph API v2.11 Required

This API is available only in Graph API v2.11 and above.

Sponsored messages are a type of paid ad that is sent directly to everyone who currently has an open chat with your Facebook Page. Sponsored messages may be sent outside the 24-hour standard messaging window, and will be labeled 'Sponsored' in the chat.

Sponsored messages can be sent two ways:

  • Messenger Platform using the /sponsored_message_ads endpoint
  • Facebook's Marketing API

This article details how to use the /sponsored_message_adsendpoint, which allows you to send sponsored messages via the Marketing API with a single request.

For more information on sending sponsored messages with the Marketing API, see the Marketing API documentation.

Contents

Requirements

To send a sponsored message, you must do the following:

  1. Be approved for the ads_management, ads_read, and manage_pages permissions.
  2. Create or use an existing Facebook Ads account.
  3. Create a Message Creative.
  4. Send a sponsored message ad.

Ad Review & Approval Process

Once a sponsored message ad is created, it is reviewed for compliance with Facebook's advertising policies. For more information on the ads review process and policies, see Advertising Policies.

Once a sponsored message ad is approved, the message will be delivered directly to all open conversations with your Page.

Creating a Sponsored Message Creative

Unlike the Send API, which allows you to define your message at the time it is sent, sponsored messages must be defined in advance. To create a sponsored message, send a POST request to the /message_creatives endpoint, where <MESSAGE_OBJECT> is any message you would normally send via the Send API.

For complete details on request properties, see Sponsored Messages Reference.

curl -X POST -H "Content-Type: application/json" -d '{    
  "messages":[
    <MESSAGE_OBJECT>
  ]
}' "https://graph.facebook.com/v2.11/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>"

On success, the Sponsored Message Ads API will return an object with a message_creative_id property that can be used to send the message:

{
  "message_creative_id": <BROADCAST_MESSAGE_ID>,
}

Supported Message Types

The Media Template is not supported for sponsored messages. For all other templates only postbacks and web url are supported.

For quick reply we don't support location quick reply.

Sending a Sponsored Message Ad

Once you have created a Message Creative, you can include it in a targeted sponsored message ad. To create a sponsored message ad, send a POST request to the /act_<AD_ACCOUNT_ID>/sponsored_message_ads endpoint, where <AD_ACCOUNT_ID> is your Facebook Ads account ID.

For complete details on request properties, see Sponsored Message Ads API Reference.

curl \
  -F 'message_creative_id=<MESSAGE_CREATIVE_ID>' \
  -F 'daily_budget=<DAILY_BUDGET_AMOUNT>' \
  -F 'bid_amount=<BID_AMOUNT>' \
  -F 'targeting=<TARGETING>' \
  -F 'access_token=<USER_ACCESS_TOKEN>' \
  "https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/sponsored_message_ads"

On success, the Messenger Platform will return a JSON string containing identifiers for the ad group and broadcast:

{
  "ad_group_id": <AD_GROUP_ID>
  "broadcast_id": <BROADCAST_ID>
  "success": <RESPONSE_STATUS>
}

Properties

Property Type Description

message_creative_id

Integer

Message Creative id

bid_amount

Integer

Bid amount set for the biding.

daily_budget

Integer

Max daily budget to spend

targeting

JSON String

Option field for ads targeting

How it Works

The sponsored_message_ads endpoint offers an interface for the sponsored messages feature of the Facebook Marketing API. The following describes how requests to the sponsored_message_ads endpoint are passed by the Messenger Platform to the Marketing API and the default values that are used.

When you send a sponsored message ad, the Messenger Platform defines an ad group and sends the sponsored message with the following request:

curl \
  -F "adset_spec={ 
    'optimization_goal' : 'IMPRESSIONS', 
    'billing_event' : 'IMPRESSIONS', 
    'bid_amount': <BID_AMOUNT>,
    'daily_budget': <DAILY_BUDGET>,
    'promoted_object': 
    { 
    	'page_id' : <PAGE_ID>
    }, 
    'campaign_spec': 
    { 
    	'buying_type' : 'AUCTION',  
    	'objective' : 'MESSAGES'
    }, 
    'targeting' : <TARGETING>
    }" \
  -F "creative=<CREATIVE_PAYLOAD>" \
  -F "access_token=<USER_ACCESS_TOKEN>" \
 "https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adgroups"