Recently we announced a new way of creating Featured Stories (previously "Sponsored Stories") on the Ads API by using action specs. These changes make the Ads API more flexible and will make it easier for developers to adapt to new story types as we launch them. We will be deprecating the old sponsored stories creative types as of May 1.
Prior to this change Sponsored Stories were defined by choosing the correct Ad Creative type for the specific Sponsored Story type. E.g. a page like sponsored story was type 9, a page post like sponsored story was type 17 etc. This made it complicated for developers to incorporate new Sponsored Story types as each Sponsored Story required different fields per story type.
By defining Sponsored Stories via Action Specs we are making it easier for new Sponsored Story types to be integrated into Ad Tool apps as they will all make use of the same standard fields.
For example, the old way of creating a Page Like Sponsored Story (Type 9) was as follows:
curl --silent --location -F "campaign_id=6004176938239"
-F "bid_type=1"
-F "max_bid=30"
-F "targeting={'countries':['US']}"
-F "creative={'type':9,'object_id':'115632122684'}"
-F "name=AdGroup Name" "https://graph.facebook.com/act_123456789/adgroups?access_token=____"
While the new Action Spec format is as follows:
curl --silent --location
-F "campaign_id=6004176938239"
-F "bid_type=1"
-F "max_bid=30"
-F "targeting={'countries':['US']}"
-F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'page\':115632122684}'}"
-F "name=AdGroup Name" "https://graph.facebook.com/act_123456789/adgroups?access_token=____"
Similarly the old way of creating a Specific Page Post like Sponsored Story (Type 25 with query template 6) was as follows:
curl --silent --location
-F "campaign_id=6004176938239"
-F "bid_type=1"
-F "max_bid=30"
-F "targeting={'countries':['US']}"
-F "creative={'type':25, 'object_id':115632122684, 'story_id':10150420410887685, 'query_templates':[6]}"
-F "name=AdGroup Name" "https://graph.facebook.com/act_123456789/adgroups?access_token=____"
While the new Action Spec format is as follows:
curl --silent --location
-F "campaign_id=6004176938239"
-F "bid_type=1"
-F "max_bid=30"
-F "targeting={'countries':['US']}"
-F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'post\':10150420410887685}'}"
-F "name=AdGroup Name" "https://graph.facebook.com/act_123456789/adgroups?access_token=____"
You will notice that the Action Spec based requests use very similar structures in a fixed format while the older process's format depended on the ad type being created. This adoption of a fixed format for defining Sponsored Stories will made it much easier for Ads API developers to support new Sponsored Stories in the future.
The following table lists a mapping from the old Sponsored Story ad creative types to the new Action Spec equivalent.
| Legacy Creative type |
Description |
Action Spec |
| 8 |
Promotes stories published through an app. |
{'action.type':'post', 'application.id':APP_ID} |
| 9 |
Promotes stories about a user liking a page/place. |
{'action.type':'like', 'page': PAGE_ID} |
| 10 |
Promoting stories about a user checking into a place. |
{'action.type':'checkin','page':PAGE_ID} |
| 10 |
Promoting stories about a user checking into any child place of this page. |
{'action.type':'checkin', 'page.parent':PAGE_ID} |
| 16 |
Promotes stories about a user using an app*. |
{'action.type':'app_use', 'application.id':APP_ID} |
| 17 |
Promotes stories about a fan liking any post from a page. |
{'action.type':'like', 'post.author':PAGE_ID,'post.wall':PAGE_ID} |
| 19 |
Promotes stories about a user liking a domain. |
{'action.type':'like', 'domain':DOMAIN_ID} |
| 19 |
Promotes stories about a user sharing something from a domain. |
{'action.type':'post', 'post.domain':DOMAIN_ID} |
| 25 + query_template=6 + auto_update=true |
Promotes stories about a fan commenting on any post from a page. |
{'action.type':'comment', 'post.author':PAGE_ID,'post.wall':PAGE_ID} |
| 25 + query_template=6 + auto_update=false |
Promotes stories about a user liking a specific page post. |
{'action.type':'like', 'post':PAGE_POST_ID} |
| 25 + query_template=7 |
Promotes stories about a user commenting on a specific page post. |
{'action.type':'comment','post':PAGE_POST_ID} |
| 25 + query_template=8 |
Promotes stories about a user RSVPing into an event. |
{'action.type':'rsvp', 'event': EVENT_ID} |
This post relates to the Ads API which is part of the Marketing API Program. Apps must be whitelisted in order to call this API. For more details on the Marketing API program and how to apply please click here.