Legacy Sponsored Messages Reference

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
• Ad Review & Approval Process
• Setup Message Creative
  • Supported Message Types
• Send a Sponsored Message
• How it Works
• Request URI
• Example Request
• Properties
  • Create Message Creative
  • Send Sponsored Message
• Response

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

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

Send Sponsored Message

Response

Create Message Creative

{
  "message_creative_id": 938461089,
}

Send Sponsored Message

{
  "ad_group_id": "6088387928148",
  "broadcast_id": "754911018029273",
  "success": true
}