Legacy Sponsored Messages Reference

Use the Marketing API for Sponsored Messages

We recomend using the fully featured Facebook's Marketing API for Messenger

The Marketing API also provides an API to estimate delivery and API to get Ad impression data.

The sponsored_message_ads endpoint gives you the ability to send sponsored messages, which are a type of paid ad that is sent directly to everyone who currently has an open chat with your Facebook Page. The sponsored_message_ads endpoint is an interface for using the sponsored message feature of the Facebook Marketing API. Note that the instructions within Facebook Marketing API show a slightly different way that achieves the same result.

For more information on using the sponsored_message_ads endpoint, see Sending Sponsored Messages.

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. Setup message creative.
  4. Send a sponsored message.

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.

Setup 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 (subject to the "Supported Message Types" restrictions below). Note that a message creative can be only sent once.

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

Currently, Sponsored Messages support the button template and generic template. Sponsored messages may contain an image, text, and either buttons or quick replies. For all templates only postbacks and web url are supported.

Note: You must specify payload or URL with the button. Sponsored Messages do not currently support location quick reply.

Send a Sponsored Message

Once you have setup Message Creative, you can include it in a targeted sponsored message. To create a sponsored message, 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"

Request URI

Create Message Creative

https://graph.facebook.com/v2.11/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>

Send Sponsored Message

https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/sponsored_message_ads

Example Request

Create Message Creative

curl -X POST -H "Content-Type: application/json" -d '{    
  "messages": [  
    {
      "dynamic_text": {
          "text": "Hi, {first_name}! Here is a message",
          "fallback_text": "Hi! Here is a message"
      }       
    }
  ]
}' "https://graph.facebook.com/v4.0/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>"

Send Sponsored Message

  curl \
  -F 'message_creative_id=938461089' \
  -F 'daily_budget=100' \
  -F 'bid_amount=400' \
  -F "targeting={'geo_locations': {'countries':['US']}}" \
  -F 'access_token=<USER_ACCESS_TOKEN>' \
  "https://graph.facebook.com/v4.0/act_<AD_ACCOUNT_ID>/sponsored_message_ads"

Properties

Create Message Creative

Property Type Description

messages

Array

The messages to send.

Send Sponsored Message

Property Type Description

message_creative_id

Integer

The ID of the Message Creative you want to send. Each message creative can only be sent once.

daily_budget

Integer

The maximum daily budget of the ad campaign for sending the sponsored message.

bid_amount

Integer

Maximum amount to bid for each message.

targeting

String

Refer Targeting Spec to set targeting.

Fields that are pre-assigned and should be excluded from targeting:

  • publisher_platforms: messenger
  • messenger_positions: sponsored_messages
  • flexible_spec: custom_audiences

access_token

String

User Access Token

Response

Create Message Creative

{
  "message_creative_id": 938461089,
}
Property Type Description

message_creative_id

Integer

The unique ID of the message creative.

Send Sponsored Message

{
  "ad_group_id": "6088387928148",
  "broadcast_id": "754911018029273",
  "success": true
}
Property Type Description

ad_group_id

Numeric

The unique ID of the advert set. An advert set is a group of adverts that share the same budget, schedule, delivery optimization and targeting.

broadcast_id

Numeric

The unique ID of the Broadcast object

success

Boolean

Response status