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. All Page permissions require App Review before your app can use them to access in.

On May 5, 2020, we released six new Page permissions to replace manage_pages and publish_pages. These permissions provide a specific set of Page-related data. This is a gradual release, you may not see the new permissions in your app dashboard until June 1, 2020.

  • If your app has already been approved to use to manage_pages or publish_pages, your app will automatically be migrated to the new permissions by June 1, 2020.
  • If your app has been submitted but not yet reviewed for manage_pages or publish_pages, the review process will continue as normal. If your app is approved, your app will automatically be migrated to the new permissions by June 1, 2020.
  • If you wish to apply, or resubmit, for Page permissions before June 1, 2020, select the permissions you see in your app dashboard, either manage_pages, publish_pages, or the new permissions. Your app will automatically be migrated to the new permissions by June 1, 2020.

The manage_pages and publish_pages permissions will be fully deprecated in May of 2022. Changes to your code must be applied before this date.

Please visit our Graph API Changelog for more information.

PermissionDescription
manage_pages Deprecated

All versions use new permissions as of June 2020. You do not need to update your code until full deprecate in May 2020.

pages_messaging

The pages_messaging permission allows your app to manage and access Page conversations in Messenger. The allowed usage for this permission is to create user-initiated interactive experiences, send customer support messages or to confirm bookings or purchases and orders. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_show_list

The pages_show_list permission allows your app to show the list of the Pages that a person manages. You can use this permission to provide API access to accounts for showing the list of the Pages that a person manages. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_ads

The pages_manage_ads permission allows your app to manage ads associated with the Page. The allowed usage for this permission is to create and manage ads for the Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_cta

The pages_manage_cta permission allows your app to carry out POST and DELETE functions on endpoints used to manage call-to-action buttons on a Facebook Page. The allowed usage for this permission is to provide API access to manage call-to-action buttons on Pages that you manage. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_engagement

The pages_manage_engagement permission allows your app to create, edit and delete comments posted on the Page. If you have access to pages_read_user_content, you can also use pages_manage_engagement to delete comments posted by other Pages. It also allows your app to create and delete your own Page's Likes to Page content. The allowed usage for this permission is to help manage and moderate content on the Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_instant_articles

The pages_manage_instant_articles permission allows your app to manage Instant Articles on behalf of Facebook Pages administered by people using your app. You can use this permission to create and update Instant Articles for Pages owned by the people who use your app. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_metadata

The pages_manage_metadata permission allows your app to subscribe and receive webhooks about activity on the Page, and to update settings on the Page. The allowed usage for this permission is to help a Page Admin administer and manage a Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_manage_posts

The pages_manage_posts permission allows your app to create, edit and delete your Page posts. If you have access to pages_read_user_content, you can also use pages_manage_posts to delete Page posts created by a user. The allowed usage for this permission is to create and delete content on a Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_read_engagement

The pages_read_engagement permission allows your app to read content (posts, photos, videos, events) posted by the Page, read followers data (including name, PSID), and profile picture, and read metadata and other insights about the Page. The allowed usage for this permission is to help a Page Admin administer and manage a Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).

pages_read_user_content

The pages_read_user_content permission allows your app to read user generated content on the Page, such as posts, comments, and ratings by users or other Pages, and to delete user comments on Page posts. It also allows your app to read posts that the Page is tagged in. The allowed usage for this permission is to read user's and other Page’s content posted on the Page if you need it to help manage the Page. You may also use this permission to request analytics insights to improve your app and for marketing or advertising purposes, through the use of aggregated and de-identified or anonymized information (provided such data cannot be re-identified).
publish_pages Deprecated

All versions use new permissions as of June 2020. You do not need to update your code until full deprecate in May 2020.

Permission Dependencies

PermissionDependent onDescription

ads_management

pages_read_engagement

To be approved for ads_management your submission must include pages_read_engagement or your app must have been approved for pages_read_engagement in a previous submission.

instagram_basic

pages_read_engagement

To be approved for instagram_basic your submission must include pages_read_engagement or your app must have been approved for pages_read_engagement in a previous submission.

leads_retrieval

pages_manage_ads pages_read_engagement

To be approved for leads_retrieval your submission must include pages_manage_ads and pages_read_engagement or your app must have been approved for pages_manage_ads and pages_read_engagement in a previous submission.

pages_manage_posts

pages_read_engagement

To be approved for pages_manage_posts your submission must include pages_read_engagement or your app must have been approved for pages_read_engagement in a previous submission.

pages_manage_engagement

pages_read_user_content

To be approved for pages_manage_engagement your submission must include pages_read_user_content or your app must have been approved for pages_read_user_content in a previous submission.

pages_messaging

pages_manage_metadata

To be approved for pages_messaging your submission must include pages_manage_metadata or your app must have been approved for pages_manage_metadata in a previous submission.

Permission Mapping

Deprecated PermissionPermission Use Cases

manage_pages

pages_manage_ads – Create, edit, and delete ads for your Page

pages_manage_metadata – Manage webhooks, update Page settings

pages_read_engagement – Read posts by your Page

– Read data of your Page followers
– Read metadata of your Page
– Read insights of your Page

pages_show_list – Get a list of Pages on which you can perform tasks

pages_read_user_content – Read User posts, comments, and ratings of your Page

– Delete User comments on your Page posts
– Read posts your Page is tagged in

publish_pages

pages_manage_posts – Create, edit, and delete your Page posts

– Delete User posts on your Page (pages_read_user_content needed)

pages_manage_engagement – Create, edit, and delete comments posted by your Page

– Delete comments posted by other Pages (pages_read_user_content needed)
– Create and delete likes posted by your Page

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

Users who interact with Pages are identified by Page-Scoped User IDs (PSID). PSIDs are IDs that are unique to each User-Page pair. Pages API and Messenger API endpoints rely on PSIDs, so you can use a PSID to identify a User's interactions with a Page, as well as the User's public Messenger conversations with that Page.

App-Scoped User IDs

Before May 1, 2018, Pages API endpoints relied on App-Scoped User IDs (ASID). Apps created before this date continued receiving ASIDs in endpoint responses, unless an app admin used the App Dashboard to opt-in to receive PSIDs. Starting with v7.0+, Pages API endpoints will only accept and return PSIDs for all apps, regardless of their creation date. This change will also be applied to all API versions on May 5th, 2021.

The Page-Scoped ID API allows you to map ASIDs to their PSID equivalents. The API is deprecated in v7.0+, but can be used with older versions until May 5th, 2021.

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.