Creating Sponsored Stories with Action Specs

Recently we announced a new way of creating 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.

Please note that query_template is being retired from the API and is not used in the Action Spec framework.

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.