Page Upcoming Changes API

This document explains how to use the Page Upcoming Changes API to view and accept or reject changes suggested by Facebook to fix possible errors on your Facebook Page.

On May 5, 2020, we released six new Page permissions to replace the manage_pages and publish_pages permissions.

Please visit our V7.0 Blog post, Graph API Changelog, and Pages API Overview for more information.

Before You Start

You will need:

Get Proposed Changes

Send a GET request to the /{page-id} endpoint with the upcoming_changes field:

curl -i -X GET "https://graph.facebook.com/{page-id}
    ?fields=upcoming_changes
    &access_token={page-access-token}"

On success, your app receives the following response:

{
  "data": [
    {
      "id": "{proposed-change-1-id}", 
      "page": {
        "name": "My Page",
        "id": "{page-id}"   
      },
      "effective_time": "2017-10-16T10:19:49+0000",
      "timer_status": "stopped",           //this proposal was accepted or rejected
      "change_type": "knowledge_proposal",
      "proposal": {
        "id": "1570719759662530",
        "category": "category",
        "current_value": "273819889375819, 161516070564222, 152142351517013",
        "proposed_value": "273819889375819, 161516070564222, 152142351517013, 273819889375819"
      }
    },
    {
      "id": "{proposed-change-2-id}",
      "page": {
        "name": "My Page",
        "id": "{page-id}"
      },
      "effective_time": "2017-11-21T07:03:54+0000",
      "timer_status": "already_fired",   //this proposal was automatically accepted
      "change_type": "knowledge_proposal",
      "proposal": {
        "id": "1603101113091061",
        "category": "category",
        "current_value": "273819889375819, 161516070564222, 152142351517013",
        "proposed_value": "273819889375819, 161516070564222, 152142351517013, 273819889375819",
        "acceptance_status": "accepted"
      }
    }
  ]
}

Accept or Reject a Proposed Change

Send a POST request to the /{proposal-id} endpoint with the accept field set to true to accept the change or false to reject it:

curl -i -X POST "https://graph.facebook.com/{proposal-id}
     ?accept=true
     &access_token={page-access-token}"

On success, your app receives the following response:

{
  "succeed": true
}

Page Change Webhooks

Subscribe to the page_upcoming_change and/or the page_change_proposal.

Your callback URL will receive the following notification for the page_upcoming_change webhook:

{
  "field": "page_upcoming_change",
  "action": "pending", // can also be accepted_manually, accepted_automatically and rejected_manually
  "value": {
    "id": "123456", // id of upcoming change
    "page": {
      "id": "7878832", // id of page where the action is taken
      "name": "Page Name"
    },
    "effective_time": "2017-03-01 12:00:00",
    "change_type": "knowledge_proposal",
    "timer_status": "active",
    "proposal": {
      "id": "id of the page change proposal",
      "category": "menu link",
      "acceptance_status": "pending", // can also be accepted or rejected
      "current_value": "https://www.oldmenu.com/",
      "proposed_value": "https://www.newmenu.com/"
    }
  }
}

Your callback URL will receive the following notification for the page_change_proposal webhook:

{
  "field": "page_change_proposal",
  "action": "created",
  "value": {
    "id": "{change-proposal-id}",
    "category": "menu link",
    "current_value": "https://www.menuold.com/",
    "proposed_value": "https://www.menunew.com/",
    "acceptance_status": "pending"
  }
}

Reference

Webhooks

Webhook FieldDescription

page_change_proposal

Get real-time notifications of proposed changes suggested by Facebook for your Facebook Page.

page_upcoming_change

Get real-time notifications about upcoming changes that will occur on your Facebook Page. These changes have been suggested by Facebook and may or may not have a deadline to accept or reject before automatically taking affect.

Page Change Proposal Categories

A Page Change Proposal is a change proposed for your Page. It contains information such as category, the current page value, and the proposed value.

Category NameParameterExample Values

Hotel Booking Service Link

place_scraped_hotel_booking_website

Current Value is always -, proposed value is a link to a hotel booking service.

Business Address

place_address

An array with format:

{"street" : "{street-change}",

"zip" : "{zip-code-change}",

"city" : "{city-name-change}"}

Only changed fields are shown in the response.

Business Type

page_business_type

E-commerce, Service Area, Public Storefront, Workplace, etc.

Category

place_topic

Financial Service, Restaurant, etc.

Coordinates

place_coordinates

Coordinates of the physical store.

Cover Photo

timeline_cover_photo

Link of the cover photo.

Email

page_email

Ex. mypagebiz@email.com

Meal Type Served

place_restaurant_good_for

Breakfast, Lunch, Dinner, and Coffee

Menu Link

place_scraped_menu

Current Value is always -, proposed value is a link to a restaurant's menu.

Open Hours

place_hours

Always Open, Permanently Closed or Hours Not Available or the values shown in the hours field.

Phone

page_phone

Ex. 650-555-1000

Place Price Range

place_price_range

$, $$, $$$, $$$$

General Services Website

place_scraped_service_website

Current Value is always -. proposed value is a website.

Website

page_website

Ex. https://MyWebsite.com