Overview

The Video API is a collection of Graph API endpoints that allow apps to publish existing videos on Pages and Groups administered by app users.

Components

Host URLs

  • https://graph-video.facebook.com — Used exclusively for publishing videos on Pages and Groups.
  • https://graph.facebook.com — Used for everything else (creating polls, getting insights, etc.).

Upload Protocols

The API supports both Resumable and Non-Resumable Upload protocols. The Resumable Upload protocol is used for sequentially uploading video chunks while the Non-Resumable Protocol is used for uploading complete videos. We recommend using the Resumable Upload protocol because it supports larger video files and allows you to handle connection interruptions more efficiently.

Resources

The API uses the following nodes.

Videos

The Video node is the API's primary resource. When you upload an existing video the API generates a Video entity and publishes it on either a Page or Group, depending on the node you target when you begin the publishing process. Videos must be published on a target node.

Pages

Videos can be published on a Group as long as the app has the appropriate Permissions and Features. In addition, the app user must be able to perform admin-equivalent Tasks on the Page, or have been granted an Admin Role on the Page via the Business Manager.

Groups

Videos can be published on a Group as long as the app has the appropriate Permissions and Features and the app user is an Admin of the Group.

Crossposted Videos

Videos that have already been published can also be published on other Pages that the app user administers without having to be reuploaded. Insights on Crossposted Videos can be returned as aggregate values (e.g. the sum of all views across all Pages) or broken down by Page.

Slideshows

You can use the API to generate a slideshow Video from a collection of images hosted on a public server.

Polls

You can use the API to create Polls on published videos and get their results.

Ads

Published Videos can be used with the Marketing API's Ad Creative endpoint to create Video Ads.

Insights

You can get insights on any published Video. Insights for Crossposted Videos can be returned as aggregate values or broken down by Page.

Webhooks

For Videos published on Pages, you can receive real-time notifications of changes to a Video's publishing status and viewer interactions by setting up Page Webhooks. Set up a callback and then subscribe to the Page topic's feed and videos fields to receive notifications. Note that notification will not be sent for videos that are uploaded as secret or no_story.

Rights Management

For Videos published on a Page, you can use the Rights Management API to create and apply copyright rules in order to discover other published Videos that may be in violation, and report them.

Requirements

Permissions

To publish on a Page, the app user must grant your app the pages_show_list, pages_read_engagement, and pages_manage_posts Permissions.

To publish on a Group, the app user must grant your app the publish_to_groups Permission.

Features

No Features are required to publish on a Page. To publish on a Group, your app must be approved for the Groups API Feature.

Admin Role

The app user must be able to perform the equivalent of ADMIN tasks on the targeted Page, or be an Admin of the targeted Group.

App Review

All Permissions and Features, with the exception of pages_show_list, require App Review.

How It Works

The general flow for publishing a Video on a Page or Group is to:

  1. Get an Access Token and appropriate Permissions from your app user.
  2. Get a list of Pages or Groups that the app user is able to perform admin-equivalent Tasks on.
  3. Provide a way for the app user to select the Page or Group where they want the Video to appear.
  4. Provide a way for the app user to select a Video to be published.
  5. Split the Video into smaller chunks.
  6. Initiate an upload session and upload the individual chunks.
  7. End the upload session.