Overview

The Pages API is a set of Facebook Graph API endpoints that apps can use to create and manage a Page's settings and content. If you are unfamiliar with the Graph API, please read our Graph API documentation before proceeding.

Components

Access Tokens

API authentication is handled through Access Tokens. Most endpoints require Page access tokens, which are unique to each Page, app user, and app, and have an expiration time. In order to get a token from an app user, the app user must own or be able to perform a Task on the Page.

You can get access tokens from your app users by implementing Facebook Login.

Permissions

Most endpoints require one or more Permissions which must be granted by your app users through the use of Facebook Login. Refer to each endpoint's reference to determine which Permissions it requires. Almost all Permissions require App Review before your app can use them in Live Mode.

PermissionDescription

manage_pages

Grants an app permission to retrieve Page Access Tokens for the Pages and Apps that the app user administers. Apps that allow users to publish posts and comments must also have the publish_pages permission.

publish_pages

Grants an app permission to publish posts and comments, to like Pages, and to view, post, and delete videos for Pages managed by the app user. Also requires the manage_pages permission.

pages_messaging

Grants an app permission to manage and access Page conversations in Messenger.

pages_show_list

Grants an app permission to retrieve a list of Pages and Page Access Tokens that the person administers.

pages_manage_cta

Grants an app permission to perform POST and DELETE operations on endpoints used for managing Call-to-Action buttons of a Page.

pages_manage_instant_articles

Grants an app permission to manage Instant Articles on behalf of a Facebook Page administered by people using your app.

Features

Some endpoints require Features which must be approved through the App Review process before your app can use them in Live Mode. Refer to each endpoint's reference to determine which Features it requires.

FeatureDescription

Live Video API

Allow apps to create LiveVideos on Pages.

Page Mentioning

Allows apps to mention other Pages when creating Posts on a Page.

Page Public Content Access

Allows apps to read public Page fields, the Page Feeds edge, Comments on Page Posts, and the Pages Search API.

Page Public Metadata Access

Allows apps to read public Page fields and the Pages Search API.

Tasks

Tasks allow Users to perform specific actions on a Page. When a User uses an app to interact with a Page, depending on the attempted action, we will first check if the User has been approved for a task that permits that type of action.

You can approve individual Users for the following tasks:

TaskPermitted Actions

ADVERTISE

Create ads and unpublished Page Posts

ANALYZE

View Insights

CREATE_CONTENT

Create Posts as the Page

MANAGE

Approve and manage Page tasks for Users

MODERATE

Respond to and delete comments, send messages as the Page

Changes

Beginning February 1, 2019, Page tasks have replaced Page roles. Under the old role-based model, assigning a role to a User granted that User permission to perform a set of actions. The new task-based model allows you to be more restrictive by only approving tasks that map to certain actions.

Use the table below to map roles to their equivalent actions:

RoleEquivalent Tasks

Admin

ADVERTISE, ANALYZE, CREATE_CONTENT, MANAGE, MODERATE

Advertiser

ADVERTISE, ANALYZE

Analyst

ANALYZE

Editor

ADVERTISE, ANALYZE, CREATE_CONTENT, MODERATE

Moderator

ADVERTISE, ANALYZE, MODERATE

Page-Scoped User IDs

When a User visits a Page, an ID is returned for that person for that specific page. The Pages API returns this Page-scoped ID, a PSID, for a User allowing your app to connect a customer's interactions with the Page across both Pages API and Messenger API. This will allow your app to connect public conversations that happen through Messenger for a given User and Page.

Before May 1, 2018, the Pages API returned App-scoped IDs, ASIDs. If your app used the Pages API and ASIDs before this date, you will need to migrate from your ASIDs to Page-scoped IDs within 180 days of your App Review approval at which time your ASIDs will no longer work. Only after you have completed the migration will your app receive PSIDs instead of ASIDs.

To facilitate the ASID to PSID migration process, use the Page-scoped ID API. This API allows you to map an ASID and a page to a PSID. You can then prepare your systems to be able to support PSIDs. Once your migration is complete we can then enable PSIDs to be returned via the Pages API endpoints.

The Page-scoped ID API will be available for 180 days from the date that your app passed App Review. The Pages API Migration section in your app's App Dashboard (Settings > Advanced > Pages API Migration) will display the number of days remaining for your app.

Rate Limits

All Pages endpoint requests are subject to Rate Limiting. You can see your app's current call count consumption in the App Dashboard.

App Review

All Page-related Permissions except for pages_show_list and all Features require approval through the App Review process before your app can use them while in Live Mode.

Apps in Development Mode can request any Permission from any app user who has a Role on the app.

How It Works

This is a typical flow for accessing the Pages API:

  1. Get a User Access Token from the app user through Facebook Login.
  2. Query the /me/accounts endpoint to get the ID and Page Access Token of the Page the app user has permitted your app to access.
  3. Capture the returned Page ID and Page Access Token.
  4. Use the ID and token to query the Page node.

Note that in some cases the app user may grant your app access to more than one Page, in which case you should capture each Page ID and its respective token, and provide a way for the app user to target each of those Pages.

Next Steps

Follow our Get Started guide to learn how to create a Page and post to it using the Pages API.