Manage Facebook Pages

With the Pages API your app can get and update page information, and change page settings.

Before You Start

You will need:

  • a Page access token requested by a person who is able to perform the task on the Page that is being queried
  • additional permissions or tasks for a specific procedure. These additional requirements are included with the procedure instructions.

Get a List of Pages, Tasks, and Tokens

You can get a list of all Pages on which you can perform a task and Page access tokens for each Page.

Additional Requirements

  • the pages_show_list or manage_pages permission
  • a User access token to list all Pages on which you can perform tasks

Send a GET request to /{user-id}/accounts endpoint:

curl -i -X GET \
     "https://graph.facebook.com/{user-id}/accounts
     ?access_token={user-access-token}"
GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{user-id}/accounts",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{user-id}/accounts"
           parameters:nil
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{user-id}/accounts',
  'GET',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{user-id}/accounts',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

On success, your app will receive the following response:

{
  "data": [
    {
      "access_token": "{facebook-for-developers-page-access-token}",
      "category": "Internet Company",
      "category_list": [
        {
          "id": "2256",
          "name": "Internet Company"
        }
      ],
      "name": "Facebook for Developers",
      "id": "{facebook-for-developers-page-id}",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT"
      ]
    },
    {
      "access_token": "{my-outlandish-stories-page-access-token}",
      "category": "Blogger",
      "category_list": [
        {
          "id": "361282040719868",
          "name": "Blogger"
        }
      ],
      "name": "My Outlandish Stories",
      "id": "{my-outlandish-stories-page-id}",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    },
    {
      "access_token": "{princess-fables-page-access-token}",
      "category": "Blogger",
      "category_list": [
        {
          "id": "361282040719868",
          "name": "Blogger"
        }
      ],
      "name": "Princess Fables",
      "id": "{princess-fables-page-id}",
      "tasks": [
        "MODERATE"
      ]
    },
...

Note that versions older than 3.1 of the API returned Page roles and their permissions however Page roles have been deprecated and replaced by Page tasks as of October 26, 2018. Visit the Overview for task to role mapping.

Get Tasks Others Can Perform on a Page

You can get a list of people who can perform a task on a Page.

Additional Requirements

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

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{page-id}",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "roles{tasks}");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}"
           parameters:@{ @"fields": @"roles{tasks}",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}',
  'GET',
  {"fields":"roles{tasks}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{page-id}?fields=roles{tasks}',
    '{page-access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X GET "https://graph.facebook.com/{page-id}
     ?fields=roles{tasks}
     &access_token={page-access-token}"

On success, your app receives the following response:

{
  "roles": {
    "data": [
      {
        "name": "Jean-Paul Jeanne",
        "id": "{user-id}",
        "tasks": [
          "ANALYZE"
        ]
      },
      {
        "name": "Kelly Hoover",
        "id": "{user-id}",
        "tasks": [
          "ANALYZE",
          "ADVERTISE",
          "MODERATE",
          "CREATE_CONTENT",
          "MANAGE"
        ]
      }
    ],
  }
}

Get Details from a Page

You can get details from a Page, such as phone, email, or hours of operation.

Additional Requirements

For people who manage the Page being queried, you will need:

For people who do not manage the Page being queried, you will need:

Send a GET request to the /{page-id} endpoint with the Page fields you would like to view:

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{page-id}",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "about,attire,bio,location,parking,hours,emails,website");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}"
           parameters:@{ @"fields": @"about,attire,bio,location,parking,hours,emails,website",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}',
  'GET',
  {"fields":"about,attire,bio,location,parking,hours,emails,website"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{page-id}?fields=about,attire,bio,location,parking,hours,emails,website',
    '{page-access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X GET "https://graph.facebook.com/{page-id} 
     ?fields=about,attire,bio,location,parking,hours,emails,website
     &access_token={page_access_token}"

On success, your app receives the following response:

{
  "about": "This a Cafe!", 
  "location": {
    "city": "Menlo Park", 
    "country": "United States", 
    "latitude": 37.482266, 
    "longitude": -122.150546, 
    "state": "CA", 
    "street": "1601 Willow Rd", 
    "zip": "94025"
  }, 
  "parking": {
    "lot": 1, 
    "street": 0, 
    "valet": 0
  }, 
  "emails": [
    "hi@hello.com"
  ], 
  "website": "http://www.cafe.com", 
  "id": "{page-id}"
}

Note, if a field is not returned in the response, the Page does not have this value set. For example, if the Page has not set the attire field, this field will not be returned in the response.

Update Details on a Page

You can update details on a Page, such as phone, email, or hours of operation.

Additional Requirements

Send a POST request to the /{page-id} endpoint with the field and value you want to update:

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}",
  new JSONObject("{\"description\":\"This is an awesome cafe!\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}"
           parameters:@{ @"description": @"This is an awesome cafe!",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}',
  'POST',
  {"description":"This is an awesome cafe!"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}',
    array (
      'description' => 'This is an awesome cafe!'
    ),
    '{page_access_token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X POST "https://graph.facebook.com/{page-id}
     ?about=This is an awesome cafe!
     &access_token={page_access_token}"

On success, your app will receive the following response:

{
  "success": true
}

Update Page Settings

You can update the settings of a Page, such as allowing visitors to post to your Page, message your Page, or age or country restrictions.

Additional Requirements

Send a POST request to the {page-id}/settings edge with the option you want to update:

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}/settings",
  new JSONObject("{\"option\":\"{USERS_CAN_MESSAGE: true}\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/settings"
           parameters:@{ @"option": @"{USERS_CAN_MESSAGE: true}",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}/settings',
  'POST',
  {"option":"{USERS_CAN_MESSAGE: true}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}/settings',
    array (
      'option' => '{USERS_CAN_MESSAGE: true}'
    ),
    '{page-access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X POST "https://graph.facebook.com/{page-id}/settings
     ?option={USERS_CAN_MESSAGE: true}
     &access_token={page-access-token}"

On success, your app will receive the following response:

{
  "success": true
}

Get Page Posts

You can get posts of a Page.

Additional Requirements

For people who manage the Page being queried, you will need:

  • the manage_pages permission
  • The person requesting the Page access token must be able to MODERATE the Page.

For people who do not manage the Page being queried, you will need:

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

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{page-id}/feed",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/feed"
           parameters:nil
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}/feed',
  'GET',
  {},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/{page-id}/feed',
    '{access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X GET "https://graph.facebook.com/{page-id}/feed
     ?access_token={access-token}"

On success, your app receives the following response:

{
  "data": [
    {
      "created_time": "2019-01-02T18:31:28+0000",
      "message": "This is my test post on my Page.",
      "id": "{page-post-id}"
    }
  ],
...

Limitations

  • Live Videos - If a Page post contains a video that has expired, such as a live broadcast, you can get some post fields but not fields related to the video. The video has its own privacy rules. If the video has expired, you must be the page admin to view its information.
  • Message CTA - Any access token can be used to request publicly shared Page posts as long as your app has been approved for the Page Public Content Access Feature. However, posts with message CTAs cannot be accessed using another Page's access token since pages cannot message other pages.

Get Page Ratings and Reviews

You can get all ratings and reviews for a Page, including the name of the reviewer and the review text.

Additional Requirements

  • The person requesting the token must be able to MODERATE the Page.

Beginning August 17, 2018 we are introducing a new ratings parameter that captures recommendations, recommendation_type with values of positive or negative. This new parameter is replacing the rating parameter with its 1 to 5 scale. Ratings created after August 13 will use this new parameter.

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

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/{page-id}",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "ratings{open_graph_story,recommendation_type,has_review}");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}"
           parameters:@{ @"fields": @"ratings{open_graph_story,has_rating,has_review}",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}',
  'GET',
  {"fields":"ratings{open_graph_story,recommendation_type,has_review}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{page-id}?fields=ratings{open_graph_story,recommendation_type,has_review}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X GET "https://graph.facebook.com/{page-id}
     ?fields=ratings{open_graph_story,recommendation_type,has_review}
     &access_token={page-access-token}"

For Pages that have both ratings and recommendation types, your app receives this response:

{
  "data": [
    {
      "open_graph_story": {
        "start_time": "2018-07-07T04:35:18+0000",
        "type": "sellers.rates",
        "data": {
          "rating": {
            "value": 5,
            "scale": 5
          },
          "is_hidden": false,
          "seller": {
            "id": "130533530354972",
            "title": "Jasper's Market",
            "type": "seller",
            "url": "https://www.facebook.com/JaspersMarket/"
          }
        },
        "id": "10150030749305470"
      },
      "created_time": "2018-07-07T04:35:18+0000",
      "rating": 5,
      "has_rating": true,
      "has_review": false,
      "recommendation_type": "positive"
    }
  ]
}

For Pages that have only recommendations, your app receives this response:

{
  "data": [
    {
      "open_graph_story": {
        "start_time": "2018-07-07T04:35:18+0000",
        "type": "sellers.rates",
        "data": {
          "is_hidden": false,
          "seller": {
            "id": "130533530354972",
            "title": "Jasper's Market",
            "type": "seller",
            "url": "https://www.facebook.com/JaspersMarket/"
          }
        },
        "id": "10150030749305470"
      },
      "created_time": "2018-07-07T04:35:18+0000",
      "has_rating": false,
      "has_review": false,
      "recommendation_type": "positive"
    }
  ]
}

Block a Person

You can block a person from commenting on a Page.

Additional Requirements

Send a POST request to the /{page-id}blocked endpoint with the ID of the person you want to block:

GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/{page-id}/blocked",
  new JSONObject("{\"user\":\"{user-id-to-block}\"}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/{page-id}/blocked"
           parameters:@{ @"user": @"{user-id-to-block}",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/{page-id}/blocked',
  'POST',
  {"user":"{user-id-to-block}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/{page-id}/blocked',
    array (
      'user' => '{user-id-to-block}'
    ),
    '{page-access-token}'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X POST "https://graph.facebook.com/{page-id}/blocked
     ?user={user-id-to-block}
     &access_token={page-access-token}"

On success, your app receives the following response:

{
  "{user-id-to-block}": true
}

Learn More