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.

Before You Start

You will need:

Get All Proposed Changes

Send a GET request to the /{page-id}/change_proposals endpoint:

curl -i -X GET "https://graph.facebook.com/{page-id}/change_proposals
     &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"
      }
    }
  ]
}

Get Proposed Changes with Deadlines

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

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

Get Change Acceptance Status

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

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

On success, your app will receive the following response:

{
  "data": [
    {
      "proposal": {
        "acceptance_status": "pending",
        "id": "{proposal-id}"
      },
      "id": "{page-id}"
    },
    {
      "proposal": {
        "acceptance_status": "accepted",
        "id": "{proposal-id}"
      },
      "id": "{page-id}"
    },
    {
      "proposal": {
        "acceptance_status": "rejected",
        "id": "{proposal-id}"
      },
      "id": "{page-id}"
    }
  ]
}

Accept a Proposed Change

Send a POST request to the /{proposal-id} endpoint with the accept field set to true:

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
}

Reject a Proposed Change

curl -i -X POST "https://graph.facebook.com/{proposal-id}
     ?accept=false
     &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

Endpoints

EndpointDescription

/{page-id}/change_proposals

Get the proposed changes suggested by Facebook for your Facebook Page.

/{page-id}/upcoming_changes

Get information 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.

include_inactive

Whether to include inactive changes such as changes that have been rejected, accepted automaticially, or accepted by a Page admin.

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