Product Docs

Login

Sharing

Web
iOS
Android
Custom Stories
Overview
Custom Stories on Web
Custom Stories in iOS
Custom Stories in Android
Using Actions
Actions
Using Objects
Creating Custom Stories
Localization
Custom Stories Insights
Submission Process
Reference
Social Plugins
Best Practices

Games

Payments

Ads for Apps

SDKs

iOS

Android

JavaScript

PHP

Unity

Third-Party

APIs

Graph API

Ads API

Using Actions

Facebook has defined a set of common actions for use in apps that describe interactions. These actions make it faster and simpler to integrate Open Graph into your apps. Actions are published, retrieved and modified using the Graph API.

You can view the full list of common actions that can be used by apps or read our Quick Start for Open Graph to learn how to get set up. This doc covers:

• Creating actions
• Publishing actions
• Reading actions
• Updating actions
• Deleting actions
• Tagging places
• Tagging friends
• Mentioning friends
• Mentioning pages
• Adding photos to stories
• Explicit sharing, used to let your users share something prominently, like they would on Facebook
• User restrictions, used to make the content available only to approved audiences
• Posting past actions
• Action links, used to associate one action with another action
• App Access Token, used to publish actions from your server
• Link referer parameters, appended to links in stories to so you can parse and analyze them

Creating Actions

Common actions do not need to be created, you can just start publishing them. They will then appear in the list of actions in your App Dashboard.

Custom actions are created by using the Open Graph tool to make a new story or by defining the action types specifically.

Publishing Actions

To publish an action, make an HTTP POST to the following Graph API endpoint:

/{user-id}/{action-type}

This call should be signed with a user access token with publish_actions permission or with an appaccess token for a user who was previously logged in.

For common actions, the {action-type} is the name of the action, such as og.likes:

/{user-id}/og.likes

For custom actions, it is a composite of the app namespace and the custom action type:

/{user-id}/{namespace}:{action-type-name}

The namespace is unique to your app, and is set in your app's dashboard on the Basic tab.

Parameters

The following parameters are used when publishing an action, any custom action properties should also be included when publishing.

Name	Type	Required	Description
object type	Reference	Yes	The type of object used here is determined by the action type being published, for example og.likes uses an object type, fitness.runs uses an coursetype. The value of this object is the URL or ID of an appropriate object instance.
start_time	DateTime	No	The time this action started.
end_time	DateTime	No	The time this action ended.
expires_in	Integer	No	The number of seconds before this action is considered “old”. From the time the action until expires_in seconds have elapsed, the action is considered “present tense”, and afterwards, it is considered “past tense”. expires_in is a shortcut for specifying end_timewhen it is more convenient to provide a delta in seconds between when an action started and when it ends. For example, when a user starts watching a movie, when you post a watch action, expires_inshould be the length of the movie in seconds
notify	Boolean	No	If false we will suppress notifications resulting from the published action. This is only applicable to likes.
privacy	JSON Object	No	A JSON-encoded object in the standard privacy parameter format that defines the privacy setting for the action.
image	String	No	The URL of an image that is added to the story and overrides the image that is associated with the object properties. See the image capabilities for information about publishing large-format photos with stories.
ref	String	No	When users click through to your site from an Open Graph action displayed in Facebook, this value will be passed in the fb_ref query parameter which Facebook will add to external links to your objects. This is useful for A/B tests and tracking other data associated with the action. By default, the ref parameter will accept 500 unique values for ref in a 7 day period. These values will be used to display graphs grouped by each unique value of ref in your application's insights. If you need more values 500 per 7 days, for example if you are passing globally unique IDs via the refparameter, you may use the "__" separator. Text to the left of the separator will be used as indexes in Insights and used to help you analyze A/B test results. Text to the right of the separator will be ignored for insights purposes, will not form part of the 500 by 7 quota, but will still be passed in thefb_ref parameter the user follows a link from the story.
scrape	Boolean	No	If true we will scrape your object and update its properties prior to creating the action. Scraping will slow down the request and has the potential to hit rate limits so only scrape when the object has been updated.
no_feed_story	Boolean	No	Setting this to true will stop the action from publishing a story to news feed. This can be helpful when you are adding multiple actions at once and do not want to spam.

Example

POST /me/cookbook:eat?
  recipe=http://www.example.com/recipes/pizza/&
  start_time=2013-03-06T15:18:26-08:00&
  end_time=2013-03-06T15:18:27-08:00&
  access_token=VALID_ACCESS_TOKEN