This endpoint is deprecated and will stop working after February 4th, 2020.
We recommend 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.
To send a sponsored message, you must do the following:
ads_management
, ads_read
, and manage_pages
permissions.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.
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>,
}
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.
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>
}
Property | Type | Description |
---|---|---|
| Integer | Message Creative id |
| Integer | Bid amount set for the biding. |
| Integer | Max daily budget to spend |
| JSON String | Option field for ads targeting |
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"
https://graph.facebook.com/v2.11/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>
https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/sponsored_message_ads
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/v9.0
/me/message_creatives?access_token=<PAGE_ACCESS_TOKEN>"
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/v9.0
/act_<AD_ACCOUNT_ID>/sponsored_message_ads"
Property | Type | Description |
---|---|---|
| Array | The messages to send. |
Property | Type | Description |
---|---|---|
| Integer | The ID of the Message Creative you want to send. Each message creative can only be sent once. |
| Integer | The maximum daily budget of the ad campaign for sending the sponsored message. |
| Integer | Maximum amount to bid for each message. |
| String | Refer Targeting Spec to set targeting. Fields that are pre-assigned and should be excluded from targeting:
|
| String | User Access Token |
{
"message_creative_id": 938461089,
}
Property | Type | Description |
---|---|---|
| Integer | The unique ID of the message creative. |
{
"ad_group_id": "6088387928148",
"broadcast_id": "754911018029273",
"success": true
}
Property | Type | Description |
---|---|---|
| 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. |
| Numeric | The unique ID of the Broadcast object |
| Boolean | Response status |