Using Actions

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

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 Open Graph stories are deprecated in Graph API 2.8. Graph API 2.7 and lower will support custom Open Graph stories according to the following schedule:

  • Support for creating new objects will end in January 2017.
  • Support for publishing existing objects will end October 2017.
  • 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

General

Like

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.

Follow

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

Save

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

Book Apps

Rate

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

Read

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

Quote

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

Achieve

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

Celebrate

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

Plays

Use the games.plays action to show someone playing your game.

News Apps

Publish

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

Restaurant Apps

Visited

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

Watch

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

Rate

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

Music actions have been deprecated and are no longer available.

Listen

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:

/{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.

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

/{user-id}/og.likes

Parameters

The following parameters are used when publishing an action:

Name Type Required Description

object type

Reference

Yes

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.

start_time

DateTime

No

The time the action started.

end_time

DateTime

No

The time the action ended.

expires_in

Integer

No

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 video.watches action would use the length of the movie for expires_in.

notify

Boolean

No

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

privacy

Object

No

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

image

String

No

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.

ref

String

No

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.

scrape

Boolean

No

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.

no_feed_story

Boolean

No

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.


Example

POST /me/books.reads?
  book=http://www.example.com/book/09485736&
  start_time=2013-03-06T15:18:26-08:00&
  end_time=2013-03-06T15:18:27-08:00&
  access_token=VALID_ACCESS_TOKEN

Response

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=http://www.example.com/book/09485736'

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:

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

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

/{user-id}/{action-type}?
  app_id_filter={app-id}

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

/{action-instance-id}

Response

An individual action instance response will look like this:

{
    "id": "1538292028372"
    "start_time": 1303502229, 
    "end_time": 1303513029, 
    "data": {
        "type": "book", 
        "url": "http://www.example.com/book/09485736/", 
        "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:

/{action-instance-id}

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)

Response

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

true

Deleting Actions

Delete any previously published actions with 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.

Response

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

true

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

fb_source

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

fb_action_ids

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.

fb_action_types

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

fb_ref

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