Using Actions

Actions are the verbs in the stories your users share to Facebook. Actions are published, retrieved and modified using the Graph API. If you want to create a richer story with your actions, you can add additional capabilities that allow people to, for example, write their own message, tag friends, and add a location.

There are two types of actions you can use:

  • Common Actions: A set of pre-defined actions that don't require additional configurations. Click an action type to see its properties and code snippets.

  • Custom Actions: If none of the common actions suit your app, you can create your own.

Note that both action types require app review and approval before your users can publish Open Graph stories with them.

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.


Use the save.saves action to show someone saving a post from Facebook.

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.

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, regardless of whether you're using a built-in or custom action.

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:


Additional Capabilities

Capabilities are additional API features for actions. You can let your users tag people, Pages or Places, upload photos, include a personalized message, or post directly to Facebook with their stories.

They require review approval before they can be published by your users.

Additional capabilities are defined by the following parameters:

Name Type Description



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.



Specifies whether the published action was explicitly shared by the user. Read the Explicit Sharing guide for more info.



The physical location represented by a Facebook Place where this action occurred, used when tagging places.


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.



Allows someone to tag people in a story. This string is composed of a comma-separated list of the tagging tokens of friends.


Before you can implement any of these capabilities, you need to enable them in the Action Types section of the App Dashboard. Select an action, scroll to the bottom of the page and select the capabilities you want to add to your action:


Your can let your users tag friends they're performing actions with using the Tags capability. Tagged friends are notified, and if they have tag review enabled, they can decide whether the story appears on their Timeline.

Make sure you follow the guidelines for tagging to be approved for this capability.

After enabliing Tags in the Action Types section of the App Dashboard, add a tags parameter to your action publishing call, where tags is a comma separated list of tagging tokens for each person. These tagging tokens are retrieved using the /user/taggable_friends Graph API edge.

Here's an example:

    POST /v2.7/me/books.reads?

You can also tag friends after publishing the original action by updating the action with the new tags.

Mentioning Friends or Pages

In contrast to tagging, mentioning lets people tag up to ten friends or Pages in a message included along with the story. Mentioned friends are notified and if they have tag review enabled they'll be given the option to approve or reject the story from their own timeline. For mentioned Pages, administrators won't be notified and a story won't appear on the Page.

Make sure you follow the guidelines for mentions to be approved for this capability.

To enable mentions, enable both the Tags and User Messages capabilities for your action type in the Action Types section of the App Dashboard. Then add a message parameter to your action publishing call, where message is a string of text created by the person using your app. This message cannot be prefilled and any apps that do so will not be approved.

Within this message, mention friends or Pages with the following syntax:


@[page-id] or @[pageURL]

You can use the /user/taggable_friends Graph API edge to generate an auto-complete list of someone's friend's names and profile photos. Don't force people to have to input their friends' Facebook IDs directly.

    POST /v2.7/me/books.reads?
    message=You should really read this book @[AaJfY_M0tTe_ZAM6P71Zr72msCJYG2EePwuyB] and @[AaK98FO-HdEWvGFwMLp0wzHlkzbng1PrcY]&

Adding User-Generated Photos

With the user-generated photos capability, you can let people upload photos they take with the camera on their mobile device. These photos will be larger on Timeline and in News Feed than stories with the regular og:image photos.

Make sure you follow the guidelines for user-generated photos to be approved for this capability.

You should note that:

  • Photos must be taken with a camera by the person publishing them.
  • Photos must be at least 480px by 480px in size.
  • Photos will be uploaded to a photo album of the format {App Display Name} Photos on a user's Timeline. If that album doesn't exist when the photo is published, it will automatically be created.
  • The published story will retain the privacy settings that a person has granted to the app. The photo itself will inherit the privacy settings of the album, which is set by the user.

Publishing user_generated Photos

After enabling User-Generated Photos in the Action Types section of the App Dashboard, add the following fields to your original API call to publish an action:

Property Type Description



The URL of the user generated photo that is to be published.



Indicates whether or not this was a user generated photo.

These are always indexed as an array, so you can supply one or more photos in a single API call.


Multiple photos:

    POST /me/books.reads?


The Place capability lets you add location information to a story and to the Places section of a person's Timeline.

To tag places, include location information in both actions and any objects for your app.

Adding location information to objects

The business, place and restaurant objects support the GeoPoint property type, which allows you to add location information to the object:

<meta property="place:location:latitude"  content="37.416382"> 
<meta property="place:location:longitude" content="-122.152659">

Adding location information to actions

To add location information to actions, enable the Places capability in the App Dashboard.

Then just add a place parameter when you make a call to publish an action:

POST /me/books.reads?

The place parameter can be one of three things:

  • The URL of an object from your app that has location information added to it.
  • The URL of an object from a third-party app that has location information.
  • The ID of a Facebook Page that is a place. You can locate the ID of the place using Graph API search and then publish the action using it.

Explicit Sharing

Stories should only be shared explicitly when people indicate that they want to share their in-app experience in the same way that they would post to Facebook themselves. Explicitly shared stories will always be posted to the Timeline of the person who shares them, and might appear in their friends' News Feeds.

Explicit sharing can happen through a variety of actions, like posting a photo or adding a message to an action they've taken. The important thing is that people clearly understand they are posting this action and must opt in to publishing this action to Facebook.

Here's an example of an app explicitly sharing content on Facebook:

The following types of actions should not generally be labeled as explicitly shared, even though they may be explicitly initiated by a person using your app:

  • Actions that occur naturally in an app, such as listening, reading, watching and using
  • Lightweight social buttons, such as like, love, favorite and save
  • Low-signal activities that happen in bulk, such as following, friending and passing
  • Functional parts of game play, such as playing, earning, building and gifting


Using the explicit action parameter

Use the fb:explicitly_shared parameter to indicate an action is explicitly shared:


Implicit sharing

There are some activities that happen naturally in the flow of your app that you may want to publish but which people may not want to highlight explicitly on the timeline. These could be actions like listening to a song or reading an article. In these cases, omit the fb:explicitly_shared parameter (preferred).

User restrictions can be applied to Open Graph stories to make the content available to approved audiences. The news feed, ticker and timeline stories can be filtered by country, age, and content. For example, a music app can specify that stories published by their app may only appear in countries in which they have launched. Alternatively a video app can restrict stories from movies rated PG13 to viewers age 13+, and restrict movies rated NC17 to viewers age 17+.

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 or myfacebookapp:mycustomaction).


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