Watch Action

For developers building video apps, Facebook provides a common Open Graph watch action.

This action can only refer to a common video-type object such as movie, tv_show, tv_episode or video.

This action and associated object types are automatically added to the App Dashboard when you use the action for the first time.

This document covers the following topics:

Code Samples

You can find platform-specific code samples on how to create, read, update, or delete a watch action in the API Reference Guide.

Explicitly Sharing Watch Actions

An app can enable people to explicitly share their watch actions. This means that the person clearly intends to share their watching activity on Facebook (for example, by clicking on a button). To explicitly share, the fb:explicitly_shared parameter must be set to true.

Best Practices

When a person starts watching any video-based content through your app, and has viewed that particular video content for at least 10 seconds, publish a story to Open Graph about the action with video as a reference to the common video-type object content.

POST[video-type content url]

You can also supply values for optional action properties such as start_time to specify when a person started watching a movie and expires_in to specify the length of a movie in seconds. By default, start_time will be set to the publish time of the Open Graph story about the activity, and expires_in will be set to the duration of the video object type.

For example, if a person watched a movie for two hours on February 20th, 2013, this activity would be published to Open Graph as:

POST /me/
  video=[movie object content url]&

This call will return an id that represents this particular instance of a movie watching activity.

If the person watches more than 50% of a video, but does not complete it, the action instance should be updated to reflect that the person has stopped watching by updating expires_in to the length of time the video was actually watched:

POST[watch action instance id]?expires_in=7054

When a person watches less than 50% of a video, or if a person removes a watch activity from your app/site, you should also remove the corresponding action instance that was published to Open Graph by invoking the following call:

DELETE[watch action instance id]

Submission Criteria

Before you submit the use of action by your app for approval, confirm your app meets all of the following requirements:

Properly Configured Objects

This action can only refer to the following objects:, video.tv_show, video.episode or video.other. As a convenience, these common video-type objects are automatically added when you register the common watch action for your app. Submission for customwatch actions is no longer accepted.

Please note that the object is reserved only for full-length, feature films (i.e. not to be used with movie trailers, movie clips, user-generated video content, etc.).

Publish Awareness

You will comply with the Video Privacy Protection Act (VPPA), and obtain any opt-in consent necessary from users so that user data subject to the VPPA may be shared on Facebook. You will represent that any disclosure to us will not be incidental to the ordinary course of your business.

You will also always provide users with a clear, ongoing, and in-context message that their watch actions will be published to Facebook.

  • Clear - a plain, easy-to-understand informative message to users
  • Ongoing - this message should appear every time a user watches a video (e.g., on the page where the user watches the video)
  • In-context - this message should be visibly close to the video that the user is watching

New User Education

If you plan on using an in-line control, your app needs to explain to users how the control works, including the fact that the app will publish watch actions to the user's timeline when sharing is enabled. If your app is streaming video, watch actions may only be published after the user has watched at least 10 seconds of the video content.


Finally, provide users with the ability to remove any video stories that your app publishes to Open Graph, and the ability to turn this sharing on or off at any time. The selection or choice made by users on their sharing preferences should be persisted.

Explict Sharing

If your watch action is not triggered by a user clicking a "play" button in a video player, you must make it clear to to the user that you will be publishing a watch story.