Manage Facebook Pages

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

Get a List of Pages, Tasks, and Tokens

Get a List of Pages

Before You Start

You will need:

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}"

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"
      ]
    },
...

Get Tasks Others Can Perform on a Page

Before You Start

You will need:

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

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"
        ]
      }
    ],
  }
}

Page Details

Get Details

Before You Start

For people who can perform tasks on your Page, 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:

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

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

Before You Start

For people who can perform tasks on your Page, you will need:

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

curl -i -X POST "https://graph.facebook.com/{page-id}
     ?about=This is an awesome cafe located downtown!
     &access_token={page_access_token}"

On success, your app will receive the following response:

{
  "success": true
}

About Story

Before You Start

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

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

Create a Story

Only people who own or manage the Page can create a Page About Story.

Send a POST request to the /{page-id}/page_about_story endpoint with parameters to set the title, the story text, and to publish the story:

curl -i -X POST "https://graph.facebook.com/{page-id}/page_about_story
     ?title=My Title 
     &composed_text=[{text:My Story text., type:UNSTYLED, depth:0}]
     &is_published=true
     &access_token={page-access-token}"

On success, your app receives the following response:

{
  "page_about_story_id": "{page-story-id}"
}

Create a Story with Inline Style Elements

Send a POST request to the /{page-id}/page_about_story endpoint with parameters to set the title, the story text with style elements, and to publish the story.

curl -i -X POST "https://graph.facebook.com/{page-id}/page_about_story
   ?title=My Story Title
   &composed_text=[        
     {
       "text":"My Facebook Story text.", 
       "type":"UNSTYLED", "depth": 0, 
       "inline_style_ranges": [
         {
           "offset": 12, 
            "length": 5, 
            "style": "ITALIC"
         }
       ]
     }
   ]
   &is_published=true
   &access_token={page-access-token}"

On success, your app receives the following response:

{
  "page_about_story_id": "{page-story-id}"
}
...
    "composed_text": [ 
      { "text": "Hello, this is the story of my cats:",
        "type": "UNSTYLED",
        "depth": 0,
        "inline_style_ranges": [{"offset": 28, "length": 7, "style": "ITALIC"}] 
      },
      { "text": "Ash, who is black with black stripes",
        "type": "UNORDERED_LIST_ITEM",
        "depth": 1,
        "inline_style_ranges": [{"offset": 0, "length": 3, "style": "BOLD"},
                                {"offset": 18, "length": 4, "style": "ITALIC"}] 
      },
      { "text": "Cinder, who is black with black stripes",
        "type": "UNORDERED_LIST_ITEM",
        "depth": 1,
        "inline_style_ranges": [{"offset": 0, "length": 6,"style": "BOLD"},
                                {"offset": 21, "length": 4, "style": "ITALIC"}]
      },
      { "text": "I adopted them from the Silicon Valley Humane Society.",
        "type": "UNSTYLED",
        "depth": 0,
        "entity_ranges": [{"offset": 24, "length": 29, "key": "0"}]
      },
      { "text": "📷",
        "type": "MEDIA",
        "depth": 0,
        "entity_ranges": [{"offset": 0, "length": 1,"key": "1"}]
      }
    ],

    "entity_map": [
      { "key": "1",
        "type": "IMAGE",
        "data": [{"key": "id", value": "1889355891120271"},
                 {"key": "src", "value": "location-of-the-image-uploaded-to-facebook"},
                 {"key": "caption", "value": "This is Cinder being lazy."},
                 {"key": "height", "value": "720"},
                 {"key": "width", "value": "960"},
                 {"key": "size", "value": "COLUMN"},
                 {"key": "float"}]
      },
      { "key": "0",
        "type": "LINK",
        "data": [{"key": "url",  "value": "http://www/svhs.com"},
                 {"key": "shimmedURL", "value": "https://..."}]
      }
    ]
...

Get a Story ID

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

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

On success, your app receives the following response:

{
  "page_about_story": {
    "id": "{page-about-story-id}",
    "page_id": "{page-id}",
    "is_published": true,
    "title": "My Story Title",
    "composed_text": [
      {
        "text": "My Story text.",
        "type": "UNSTYLED",
        "depth": 0
      }
    ]
  },
  "id": "{page-id}"
}

Update a Story

Only people who own or manage the Page can update a Page About Story.

Send a POST request to the /{page-story-id} endpoint with the parameters you would like to update:

curl -i -X POST "https://graph.facebook.com/{page-story-id}
     ?composed_text=[{"text": "My longer story text."}]
     &access_token={page-access-token}"

On success, your app receives the following response:

{
  "id": "{page-story-id}"
}

Delete a Story

Only people who own or manage the Page can delete a Page About Story.

Send a DELETE request to the /{page-story-id} endpoint where {page-story-id} is the ID of the Page Story you want to delete:

curl -i -X DELETE "https://graph.facebook.com/{page-story-id}
     ?access_token={page-access-token}"

On success, your app receives the following response:

{
  "success": true
}

Reference

page_about_story ParametersDescription
composed_text
JSON array,Required

The text, image, etc. of your story, including styling.

depth
int, optional

The indent value of text. Only takes effect when type is UNORDERED_LIST_ITEM or ORDERED_LIST_ITEM

entity_ranges
array, optional
  • offset: The index of the entity from the left side border where index starts at 0. non-negative int
    • For IMAGE, this should be 0, since image itself always take up a block
    • For LINK, for example, your text is “Welcome to Facebook” and you want “Facebook” to be a link. Set offset to 10, since “F” is the 10th character, and length to 8.
  • length: The number of characters of the entity. non-negative int
    • For IMAGE, this should be 1
    • offset plus length cannot be greater than the length of the text content.
  • key: Used to find the entity in entity_map. int
inline_style_ranges
array, optional

Should be the same value as

composed_text[entity_ranges]
text
int, optional

Should be the same value as

composed_text[entity_ranges]
type
int, optional

Should be the same value as

composed_text[entity_ranges]
cover_photo
dictionary, optional

The cover photo of your Page About Story.

  • photo_id: ID of the photo that has already been uploaded to Facebook. Learn more about the Photo node and Page photos.int, required
  • x_offset: horizontal offset int, optional
  • y_offset: horizontal offset int, optional horizontal offset
entity_map

Description of an entity map.

array, optional
caption

Description under the image.

string, optional for IMAGE
key

Should be the same value as

composed_text[entity_ranges]int, required
photo_id

Photo ID

int, required for IMAGE
position

LEFT, RIGHT, CENTER, default is CENTER

enum, optional for IMAGE
size

COLUMN, LARGE, MAXIMUM, default is NONE. Only takes effect when when position is CENTER.

enum, optional for IMAGE
type

IMAGE or LINK

enum, required
url

A link within your text.

string, required for LINK
is_published

Returns if the Page About Story is published or not.

boolean, optional
title

The title of your Page About Story.

string, optional

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.

Before You Start

You will need:

  • The pages_manage_metadata permission
  • A Page access token requested by a person who can perform the [MANAGE task](/docs/pages/overview-1#tasks] on the Page that is being queried

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

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 Ratings and Reviews

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

You will need:

  • The pages_manage_metadata permission
  • A Page access token requested by a person who can perform the [MANAGE or MODERATE task](/docs/pages/overview-1#tasks] on the Page that is being queried

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:

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.

Before You Start

You will need:

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

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