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 Getting Started guide for Open Graph to learn how to get set up. This doc will show you how to make API calls for:
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.
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 app access 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 following parameters are used when publishing an action, any custom action properties should also be included when publishing. The symbol indicates a required property:
Name | Description |
object type
Reference |
The type of object used here is determined by the action type being published, for example og.likes uses an |
start_time
DateTime |
The time this action started. |
end_time
DateTime |
The time this action ended. |
expires_in
Integer |
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”.
|
notify
Boolean |
If false we will suppress notifications resulting from the published action. This is only applicable to likes. |
privacy
JSON Object |
A JSON-encoded object in the standard privacy parameter format that defines the privacy setting for the action. |
image
String |
The URL of an image that is added to the story and overrides the image that is associated with the object properties. See the |
ref
String |
When users click through to your site from an Open Graph action displayed in Facebook, this value will be passed in the |
scrape
Boolean |
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 |
Setting this to |
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
Capabilities are additional API features for actions; they are optional but enabling them requires additional review during the approval process before they can be used by people who aren't developers or testers of the app (see Guidelines for Action Capabilities):
message
String |
Allows users to write a personalized message attached to this action. You can only use this when the text is entered by the user and not pre-populated. You can mention users and pages inline using mention tagging. |
fb:explicitly_shared
Boolean |
Specifies whether the published action was explicitly shared by the user. Read the Explicit Sharing guide for more info. |
place
Place |
The physical location represented by a Facebook Place where this action occurred, used when tagging places. |
image |
Various parameters that when used together indicate the inclusion of user generated photos that display in a large format. Read the adding photos to stories guide for full parameter information. |
tags
String |
Allows someone to tag people in a story. This string is composed of a comma-separated list of the IDs of those who are to be tagged. |
POST /me/cookbook:eat?
recipe=http://www.example.com/recipes/pizza/&
place=http://www.example.com/places/123/&
tags=123456&
message=Check out this amazing recipes&
access_token=VALID_ACCESS_TOKEN
After an action is successfully published, the following response will be sent:
{
id: “{action-instance-id}”
}
If you have configured action links in the App Dashboard you can suppress the action link appearing for a particular story. To do this when you publish the action pass in no_action_link=true. Read more about Action Links.
The start_time
and end_time
can be used to describe actions that have taken place in the past, as well as actions that started in the past but are currently ongoing. The tense of the action can also be changed after publishing by updating the time parameters.
Once an action has been published, the Action Instance ID can be used to like or comment on it as with any other Post object. Read the likes and comments connections of the Post object to understand how to do this.
Apps can read common actions published on behalf of a user whenever they have the relevant Open Graph Permissions by issuing an HTTP GET request to the following Graph API endpoint:
/{user-id}/{action-type}
Custom actions are slightly different, but can also be read with the user_actions:NAMESPACE
Permission:
/{user-id}/{namespace}:{action-type-name}
Individual action instances can also be retrieved by making an HTTP GET to their ID on the Graph API, with the same Permissions as above:
/{action-instance-id}
An individual action instance response will look like this:
{
"id": "1538292028372"
"start_time": 1303502229,
"end_time": 1303513029,
"data": {
"type": "recipebox:recipe",
"url": "http://www.example.com/pumpkinpie.html",
"id": "1234567890",
"title": "Pumpkin Pie"
},
}
An app can update any actions that it has previously published by making the following HTTP POST call to the Graph API:
/{action-instance-id}
This call should be accompanied by any of the parameters listed in the Publishing Actions section, with the updated value included. This call must also be made with the same types of access token that are valid for Publishing.
If the update is successful, the following response will be sent:
true
An app can also delete any actions that it has previously published by making the following HTTP DELETE call to the Graph API:
/{action-instance-id}
This call must also be made with the same types of access token that are valid for Publishing.
If the deletion is successful, the following response will be sent:
true