Using Actions

Actions are the verbs in the stories your users share to Facebook. Actions are published, retrieved and modified using the Graph API.

Open Graph offers a set of pre-defined actions that don't require additional configurations. For a list of these actions, see Open Graph Reference. Click an action type to see its properties and code snippets.

List of Common Actions



Developers can design how like fits into the core user experience of any Open Graph-integrated app by building a custom in-app Like button that works across any mobile and web platform.


Use the og.follows action to show when someone subscribes to another person's activity in your app.

Book Apps


Use the books.rates action to show someone has rated a book with your app.


Use the books.reads action to show someone has read a book with your app.


Use the books.quotes action to show someone has quoted from a book with your app.

Wants to Read

Use the books.wants_to_read action to show someone has said they want to read a book with your app.

Fitness Apps

Bike, Walk, Run

Use the fitness.bikes, fitness.walks and fitness.runs actions to show someone's workout with your app.

Game Apps


Use the games.achieves to show someone reaching a game achievement.


Use the games.celebrate action to show someone celebrating a victory in a game.


Use the games.plays action to show someone playing your game. This action shows up only in people's activity log.


Use the games.saves action to show someone saving a game.

News Apps


Use the news.publishes action to show someone publishing a news article.

Restaurant Apps


Use the restaurant.visited action to show someone has visited a restaurant.

Wants to Visit

Use the restaurant.wants_to_visit action to show someone indicating they want to visit a restaurant.

Video (Movie and Television) Apps


Use the action to show someone has watched a video with your app.


Use the video.rates action to show someone has rated a video with your app.

Wants to Watch

Use the video.wants_to_watch action to show someone has said they want to watch video with your app.


Music actions have been deprecated and are no longer available.


We are currently not accepting any new submissions for the music.listens action.

Create a Playlist

We are currently not accepting any new submissions for the music.playlists action.

Publishing Actions

Before you publish an action, you may want to set geographic restrictions under Advanced in the Action Types tab of your App Dashboard.

You'll have to publish test actions before you can submit your actions for review.

Using the Share Dialog

The simplest way to publish actions is to use the Facebook Share dialog. To get the code for these actions and objects, see our Open Graph reference section.

Using a Custom Interface

If you want to use your own publishing interface, you can use the Graph API endpoints we provide.

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


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.

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



The following parameters are used when publishing an action:

Name Type Required Description

object type



Object type is determined by the action type being published, for example og.likes uses an object type, fitness.runs uses a course type. The value of this object is the URL or ID of the object instance.




The time the action started.




The time the action ended.




The number of seconds before an action becomes past tense in stories published to Facebook. It's useful when it's easier to provide a delta in seconds between when an action starts and ends than to set an end_time. For example, a action would use the length of the movie for expires_in.




If false we'll suppress notifications resulting from the published action. This is only applicable to Likes.




The privacy settings of the action as defined by the API publishing parameters.




The URL of an image that is added to the story. It overrides the image associated with the object properties. See the image capabilities for information about publishing large-format photos with stories.




This value is passed in the fb_ref query parameter when users click through to your site from a story. Facebook will add it to external links to your objects.

The ref parameter accepts 500 unique values in a 7 day period. These values are used to display graphs grouped by each unique value of ref in your app's insights.

If you need more than 500 values per 7 days, for example if you're passing globally unique IDs via the ref parameter, you may use the "__" separator. Text to the left of the separator will be used as indexes in Insights and 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 the fb_ref parameter when the user follows a link from the story.




If true we'll scrape your object and update its properties before creating the action. Scraping will slow down the request and could hit rate limits, so only scrape when the object has been updated.




Setting this to true will stop the action from publishing a story to news feed. This is useful when adding multiple actions at once without spamming.


POST /me/books.reads?


When an action has been published, this response will be sent:

  id: “{action-instance-id}”

Publishing Past Actions

The start_time and end_time can be used for actions that took place or began in the past. You can change the tense of the action after publishing by updating the time parameters.

Just set the start_time on your action to the appropriate date in the past. For example:

curl -X POST \
     -F 'access_token=USER_ACCESS_TOKEN' \
     -F 'start_time=2011-11-13T16:21:35+0000' \
     -F 'book='

When you publish any action and set the start_time to be more than three days in the past, it will act a little differently than actions taken in the present. Specifically, past actions:

  • are not displayed on the person's Ticker or News Feed
  • are shown in Timeline at the appropriate past date
  • will appear in the person's Activity Log, with a small clock icon next to the story
  • may trigger a notification

Your app should still prompt people with explicit controls before posting past actions back to Timeline.

Interacting with Published Actions

Once an action has been published, the action instance ID can be used to like or comment on it like any other Post object. See the API Reference for these edges.

Reading Actions

Read actions published on behalf of a user with the relevant permissions by issuing an HTTP GET request to the following Graph API endpoint:


See all the actions published by an app with the app_id_filter request parameter:


Retrieve individual action instances by making an HTTP GET to the action ID on the Graph API, with the same permissions as above:



An individual action instance response will look like this:

    "id": "1538292028372"
    "start_time": 1303502229, 
    "end_time": 1303513029, 
    "data": {
        "type": "book", 
        "url": "", 
        "id": "1234567890", 
        "title": "Book Title"

Updating Actions

An app can update any actions it has previously published by making the following HTTP POST call to the Graph API:


This call should include the appropriate parameters, with the updated value included. This call must also be made with the same types of access tokens that are valid for publishing.(Note : privacy param cannot be updated for actions)


If the update is successful, this response will be sent:


Deleting Actions

Delete any previously published actions with the following HTTP DELETE call to the Graph API:


This call must also be made with the same types of access token that are valid for publishing.


If the deletion is successful, this response will be sent:


App-Level Restrictions

An app-level restriction is applied through the App Dashboard Advanced settings:

  • Country Restrictions - Enter one or more countries to specify that your app will only be visible to people in the listed countries. If no countries are listed, your app will be visible to people located in all countries. You understand that you are responsible for setting the proper country restrictions to ensure that the content of your app is appropriate for the country or countries where you allow it to be visible. Use the type ahead to specify the countries to whitelist your app for.

  • Age Restrictions - Selecting an age restriction means that anyone under the specified age will not be able to find your app in search or on friends' profiles or view the content in other ways. Age ranges for the logged in user will be returned in the signed_request (see Age Object) for Canvas Apps and should be used to help restrict content accordingly.

  • Content Restrictions restricts the app use based on content. The Alcohol-Related age restriction sets the minimum age based on the location of the user. Only users in Canada, South Korea or Nicaragua who are 19+, in Japan, Iceland or Paraguay who are 20+, in Cameroon, Micronesia, Palau, Solomon Islands, Sri Lanka or the U.S. who are 21+, in India and Sweden who are 25+, and elsewhere who are 18+ will be able to view your app. You understand that the Alcohol-Related age restriction is for convenience and that Facebook does not represent that by using that setting your app will be legally compliant in all countries where your app is visible. You understand that ultimately you are responsible for setting the proper legally compliant age restrictions for each country where your app is visible.

If there are multiple restrictions applied against a story the most restrictive option will be applied. For example, if you select 17+ age restriction and alcohol content restriction, then users in locations where the law restricts alcohol content being shown to users over 21 years, then those user would not be able to view the content. In this example, the 21+ year is the most restrictive option and will be applied.

Link Referer Parameters

Open Graph stories that are generated and displayed in Timeline or News Feed may have several links associated with them. Parameters are appended to these links so that sites can parse and analyze them.

Parameter Description


The type of Facebook story that is the origin of the link. Can be one of the following:

  • recent_activity
  • home_multiline
  • ticker_multiline
  • tickerdialog_multiline


A comma-separated list of action IDs. An action ID is the unique ID (e.g., 662453805256) corresponding to the unique instance of the Open Graph action.


A comma-separated list of action types. Action types are defined by your Facebook application (e.g., news.reads).


A comma-separated list of refs. This is optional and only present if a ref on an action is part of the story.)