Page

This document contains the following topics:

Introduction
Fields
Connections
Realtime Updates
Page Access Tokens
Page Admin Roles
Updating Page Attributes
Unpublished and Scheduled Page Posts
Feed
Types of Page Posts
Targeting Page Posts

Introduction to Pages via the Graph API

A Page in the Graph API.

The fields shown below are some of the common fields of Facebook Pages. Pages may also contain other (or additional) category-specific fields. Access to certain Pages may be restricted based on demographic information such as the current user's age or location. Access may also be restricted to only a Page's administrators.

To read a Page you need:

an app or user access token for public and non-demographically restricted pages
a user access_token for restricted pages that the current user is able to view (no special permissions required)

Example

The Page for Facebook Platform:

https://graph.facebook.com/19292868552

Fields

Name	Description	Permissions	Returns
`id`	The Page's ID	No access token or user `access_token`	`string`
`name`	The Page's name	No access token or user `access_token`	`string`
`link`	Link to the page on Facebook	No access token or user `access_token`	`string` containing a valid URL
`category_lists`	The Page's categories	No access token or user `access_token`	`string`
`is_published`	Indicates whether the page is published and visible to non-admins	No access token or user `access_token`	`boolean`
`can_post`	Indicates whether the current session user can post on this Page	No access token or user `access_token`	`boolean`
`likes`	The number of users who like the Page - For Global Brand Pages this is the count for all pages across the brand	No access token or user `access_token`	`number`
`location`	The Page's street address, latitude, and longitude (when available)	No access token or user `access_token`	`dictionary`
`phone`	The phone number (not always normalized for country code) for the Page	No access token or user `access_token`	`string`
`checkins`	The total number of users who have checked in to the Page	No access token or user `access_token`	`number`
`picture`	Link to the Page's profile picture	No access token or user `access_token`	`string`; If the "October 2012 Breaking Changes" migration setting is enabled for your app, this field will be an object with the `url` and `is_silhouette` fields; `is_silhouette` is `true` if the user has not uploaded a profile picture
`cover`	The `JSON` object including `cover_id` (the ID of the photo), `source` (the URL for the cover photo), and `offset_y` (the percentage offset from top [0-100])	No access token or user `access_token`	`JSON` object
`website`	Link to the external website for the page	No access token or user `access_token`	`string`
`talking_about_count`	The number of people that are talking about this page (last seven days) - For Global Brand Pages this is the count for all pages across the brand	No access token or user `access_token`	`number`
`global_brand_parent_page`	`Id` of this page and `JSON Object` with the `name`, `category` and `id` of the brand's parent page	No access token or user `access_token`	`dictionary`
`access_token`	A Page admin `access_token` for this page; The current user must be an administrator of this page; only returned if specifically requested via the `fields` URL parameter	`manage_pages`	`string`
`hours`	An updatable `JSON` object of the days when the business is open with keys like `sat_1_open`, `sat_1_close`, `sat_2_open`, `sat_2_close` and values like `08:00` and `17:00`	No access token or user `access_token`	`JSON` object

Connections

Name	Description	Permissions	Returns
feed	The Page's wall.	any valid `access_token` or user `access_token`	`array` of `Post` objects.
picture	The Page's profile picture.	No access token or user `access_token`.	HTTP 302 redirect to URL of the page's profile picture (use `?type=square` \| `small` \| `normal` \| `large` to request a different photo). If you specify `?redirect=false`, this connection will return the URL of the profile picture without a 302 redirect. Additionally, you can specify `width` and `height` URL parameters to request a picture of a specific size. This will return an available profile picture closest to the requested size and requested aspect ratio. If only `width` or `height` is specified, we will return a picture whose width or height is closest to the requested size, respectively; if `width`=`height`, we will always return a square picture. If the "October 2012 Breaking Changes" migration setting is enabled for your app, this connection will return a JSON object with `url`, `width`, `height`, and `is_silhouette` fields, where the width and height specify the actual dimensions of the returned picture; `is_silhouette` is a boolean which specifies whether the profile picture is the default picture (i.e. the page has not uploaded a profile picture).
settings	The settings for this page.	page `access_token`	`array` of objects containing `setting` and `value` fields.
tagged	The photos, videos, and posts in which the Page has been tagged.	any valid `access_token` or user `access_token`	a heterogeneous `array` of `Photo`, `Video` or `Post` objects.
links	The Page's posted links.	any valid `access_token` or user `access_token`.	`array` of `link` objects
photos	The Page's uploaded photos.	any valid `access_token` or user `access_token`	`array` of `Photo` objects.
albums	The photo albums the Page has uploaded.	any valid `access_token` or user `access_token`	`array` of `Album` objects.
statuses	The Page's status updates.	any valid `access_token` or user `access_token`	`array` of `Status message` objects.
videos	The videos the Page has uploaded.	any valid user `access_token`	`array` of `Video` objects.
notes	The Page's notes.	any valid `access_token` or user `access_token`	An array of `Note` objects.
posts	The Page's own posts.	any valid `access_token` or user `access_token`	`array` of `Post` objects.
promotable_posts	The Page's own posts, including unpublished and scheduled posts	any valid `access_token` or user `access_token`	`array` of `Post` objects.
questions	The Page's questions.	any valid `access_token` or user `access_token`	`array` of `Question` objects.
events	The events the Page is attending.	any valid `access_token` or user `access_token`	`array` containing `event id`, `name`, `start_time`, `end_time`, `location` and `rsvp_status`
checkins	Checkins made to this Place Page by the current user, and friends of the current user.	`user_checkins` or `friends_checkins`	`array` of `Checkin` objects.
admins	A list of the Page's Admins.	Page admin `access_token`	`array` of objects containing `id`, `name`.
conversations	A list of the Page's conversations.	Page admin `access_token` with `read_page_mailboxes` permission	`array` of objects containing conversation objects.
milestones	A list of the Page's milestones.	Page admin `access_token`	`array` of `Milestone` Objects.
blocked	A list of users blocked from the Page.	Page admin `access_token`	`array` of objects containing `id`, `name`.
tabs	The Page's profile tabs.	Page admin `access_token`	`array` of objects containing `id`, `name`, `link`, `application`, `custom_name`, `is_permanent`, `position`, and `is_non_connection_landing_tab`.
global_brand_children	Expose information of all children Pages.	Any valid `access_token` or user `access_token`	`array` of `JSON` objects containing the `id`, `name` and `category` of all Pages which are children of this one.
insights	The Page's Insights data	A valid `access_token` with `read_insights` permission for a user authorized to view the Page's insights.	`array` of `Insights` objects. See the Insights documentation for more information.

NOTE: For connections that require an access token, you can use any valid access token if the page is public and not restricted. Connections on restricted pages require a user access token and are only visible to users who meet the restriction criteria (e.g. age) set on the page.

Realtime Updates

The Page object supports Realtime Updates for the following fields and connections:

name
category_lists
picture
checkins
feed

When you subscribe to realtime page updates, the callback URI you specify will be called whenever there's a change on the page. In general, you will receive updates within a couple of minutes from when an action takes place. The delay may be longer or shorter, depending on load factors.

Note: Realtime updates are not yet supported for the total number of Page checkins.

Note: If you've previously had realtime set up with your app, you will need to log into the realtime section of the app dashboard and click 'Save Changes' to enable page updates. New realtime apps will not require this step.

Adding an App to Get Realtime Updates

Adding an app to get realtime updates is done via a special API call. There is no user interface to add an app that receives realtime updates.

In order to set up an app to get real time updates you need to:

Set up an app to receive updates. This is outlined in the introduction of the realtime updates API page. This just defines a verification key and an API endpoint for Facebook server's to call. Please test your endpoint by using the Test button in the realtime setup section of the app dashboard.
Once you've got an API endpoint up and running and tested, you need to add the app to your page. In order to do this, you will need an access_token for the page. The easiest way to get an access token is to visit /me/accounts from the graph explorer from an account that administers the page. You want the access token listed under the page in the accounts output. (You can use the debugger to see what capabilities a token has. It's important that the scopes field includes manage_pages and that the Profile ID matches the page you want to manage. The wrong token will generate a #210 error.)
Make a POST call to the page API endpoint /<page id>/tabs with app_id set to your app's ID. For example in the graph explorer you would set the access token and then call:

A successful call will return true. Assuming that you've tested your endpoint when you set up the app, you should start receiving updates.

Note: You might think that because you're adding this via the tabs API that this is a tab app. It's not. This app isn't visible to users as a page app and isn't managed via any UI. Realtime apps only need minimal configuration. All you need is to have the basic app configuration set up and then configure your realtime callback. Don't add this app as a Page Tab app in the App Dashboard's Basic configuration area.

Deleting an App

At this time there isn't a way to remove an app from getting realtime updates.

Examples

Here are some examples of data you will receive when activity occurs on a page. Note that the API will batch updates together, so it's very likely that you will see more than one entry when you receive callbacks on busy pages.

Feed Example: Like

{
    "object": "page",
    "entry": [
        {
            "id": "408518775908252",
            "time": 1360643280,
            "changes": [
                {
                    "field": "feed",
                    "value": {
                        "item": "like",
                        "verb": "add",
                        "user_id": 5900878
                    }
                }
            ]
        }
    ]
}

Feed Example: Comment

{
  "object":"page",
  "entry": [
    {
      "id":"408518775908252",
      "time":1366411040,
      "changes": [
        {
          "field":"feed",
          "value":
            {
              "item":"comment",
              "verb":"add",
              "comment_id":"439043792855750_60130047",
              "parent_id":439043792855750,
              "sender_id":738229837,
              "created_time":1366411040
            }
        }
      ]
    },
    {
      "id":"408518775908252",
      "time":1366411045,
      "changes": [
        {
          "field":"feed",
          "value":
            {
              "item":"comment",
              "verb":"add",
              "comment_id":"439043792855750_60130048",
              "parent_id":439043792855750,
              "sender_id":506640398,
              "created_time":1366411045
            }
        }
      ]
    }
  ]
}

Feed Example: Post

{
  "object": "page",
  "entry": [
    {
      "id": "408518775908252",
      "time": 1360637562,
      "changes": [
        {
          "field": "feed",
          "value": {
            "item": "post",
            "verb": "add",
            "post_id": 410746582352138
          }
        }
      ]
    }
  ]
}

Page Access Tokens

To perform the following operations as a Page, and not the current user, you must use the Page's access token, not the user access token commonly used for reading Graph API objects. This access token can be retrieved by issuing an HTTP GET to /USER_ID/accounts with the manage_pages permission. This will return a list of Pages (including application profile Pages) to which the user has administrative access, along with access_tokens for those Pages. Alternatively, you can get a page access token for a single, specific, page by issuing an HTTP GET to /PAGE_ID?fields=access_token with the manage_pages permission, as described above. Publishing to a Page also requires the publish_stream permission, unless otherwise noted.

Page Administrators have different roles, and the functionality available to them is decided based on the following roles:

Page Admin Roles

Permission/Role	Description	Full Admin	Content Creator	Moderator	Ads Creator	Insights Manager
`ADMINISTER`	Manage admins	Yes
`EDIT_PROFILE`	Edit the Page and add apps	Yes	Yes
`CREATE_CONTENT`	Create posts as the Page	Yes	Yes
`MODERATE_CONTENT`	Respond to and delete comments, send messages as the Page	Yes	Yes	Yes
`CREATE_ADS`	Create ads and unpublished page posts	Yes	Yes	Yes	Yes
`BASIC_ADMIN`	View Insights	Yes	Yes	Yes	Yes	Yes

Updating Page Attributes

You can update a Page's basic attributes or About section by issuing an HTTP POST request to PAGE_ID with Page Access Tokens that has manage_pages permission and following parameters:

Parameter	Description	Type	Required
`about`	Text for the about section of a page	`string`	N
`description`	The description of a page	`string`	N
`general_info`	The general information for a page	`string`	N
`website`	The website URL for a page	`string`	N
`phone`	The Phone number for a page	`string`	N

Setting a Page Profile Photo

You can set the profile photo for a Page by issuing an HTTP POST to /PAGE_ID/picture with a Page Access Token and one of the following parameters:

Parameter	Description	Type	Required
`picture`	A URL to the photo	`string`	N
`source`	Photo content	`multipart/form-data`	N

Setting a Cover Photo

You can set a cover photo for a Page by issuing an HTTP POST to /PAGE_ID with a Page Access Token and the following parameters:

Parameter	Description	Type	Required
`cover`	The ID of the photo	`integer`	Y
`offset_y`	The percentage offset from top (0-100). The default value is `50`	`integer`	N
`no_feed_story`	The flag indicating whether or not to create a story. The default value is `false`	`boolean`	N

Hiding a Page Post

You can hide a Page post that is published by a non-admin user by issuing an HTTP POST to /POST_ID with the following parameter:

Parameter	Description	Type	Required
`is_hidden`	Whether a post is hidden	`boolean`	Y

Unpublished / Scheduled Page Posts

A Page Post (including Photos, Videos, Status Updates & Link Shares) can be:

"Unpublished", i.e. not shown to a user or on the Page's timeline - but can be promoted
"Scheduled", i.e. to be published at a later time

The specific parameters to use when creating such posts are described in their respective sections. These posts can only be made on behalf of the page itself using the Page access token, not on behalf of users.

Updating unpublished/scheduled posts is possible by using the Post ID that is returned when creating a post. We support two types of updates on such posts:

Publishing a previously unpublished post. (Unpublishing a post is not supported)
Changing the schedule (i.e. Rescheduling, Adding schedule to an unpublished post, Removing schedule from a post thus making it unpublished.)

To publish an unpublished post, simply set the is_published variable to true via an API call.

When changing the schedule of a post, the new timestamp value should be specified as one of the following:

A valid scheduled publish time value: this will set the post to be published at the specified time. If the post was never scheduled before, it will now become scheduled. If the post had been scheduled before, it will be rescheduled for the new time.
0: this will cancel the scheduled post, turning it into an unpublished post with no associated schedule publish time. Scheduled posts cannot be canceled or rescheduled within 3 minutes of their scheduled publish time (these requests will fail). The new scheduled publish time must be greater than 10 minutes from now and less than 6 months from now.

The unpublished posts can be queried through the FQL Stream table with parameter is_published=0, example:

 select post_id, source_id, message from stream where
 source_id=<pageid> and is_published=0

Following is an example for querying both published and unpublished posts:

 select post_id, source_id, message from stream where 
 source_id=<pageid> and (is_published=0 or is_published=1)

The scheduled posts can be queried directly using the Post ID through the Graph API.

Any promotable posts (i.e. published + unpublished, including scheduled posts) can be queried via the endpoint graph.facebook.com/<pageid>/promotable_posts

feed

This connection corresponds to the Page's Wall. You can create a link, post or status message by issuing an HTTP POST request to the PAGE_ID/feed connection. To see more details please see links, posts, and status messages documentation.

To impersonate the Page when posting to the wall (i.e. post as the Page, and not the current user), you must use a Page access_token with the manage_pages and publish_stream permissions, as described under Page Access Tokens above.

Posts may be targeted to countries, cities, regions or locales using the targeting parameter. Please see posts for additional information.

Types of Page Posts

Following are the different types of Page Posts:

Events
Links
Notes
Photos
Milestones
Questions
Status Updates
Videos
Offers

events

Create

You can create an event for a page by issuing an HTTP POST request to PAGE_ID/events with the create_event permissions and the following parameters.

NOTE - After the 'Events Timezone' migration, all event times are ISO-8601 formatted strings; they can no longer be specified as timestamps. The following formats are accepted:

Date-only (e.g., '2012-07-04'): events that have a date but no specific time yet.
Precise-time (e.g., '2012-07-04T19:00:00-0700'): events that start at a particular point in time, in a specific offset from UTC. This is the way new Facebook events keep track of time, and allows users to view events in different timezones.

Event times with a date and time but no offset from UTC are no longer accepted.

Parameter	Description	Type	Required
`name`	Event name	`string`	yes
`start_time`	Event start time, in ISO-8601	`string`	yes
`end_time`	Event end time, in ISO-8601	`string`	no
`description`	Event description	`string`	no
`location`	Event location	`string`	no
`location_id`	Facebook Place ID of the place the Event is taking place	`string`	no
`ticket_uri`	URI to a location where attendees can buy tickets to this event. Note: You need to have the Events Timezone Migration turned on to use this.	`string`	no

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new event ID	`string`

Edit

You can edit an event by issuing an HTTP POST to /EVENT_ID with the create_event permission. Note that only the application that created the event can edit the event. Any of the fields listed above as being available when creating an event can be edited by specifying a new value for that field. You don't need to specify values for fields you are not editing. Note that the name and time cannot be changed if the event is old, or if it has over 5000 attendees.

If the edit is successful, you get the following return.

Type	Description
`boolean`	True if the edit succeeded and error otherwise.

Delete

You can delete an event by issuing an HTTP DELETE to /EVENT_ID with the create_event permission. Note that only the application that created the event can delete the event.

If the delete is successful, you get the following return.

Type	Description
`boolean`	True if the delete succeeded and error otherwise.

links

Create

You can post a link on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`link`	Link URL	`string`	yes
`message`	Link message	`string`	no
`picture`	Link picture. If this field is not provided, the link will be followed to retrieve an image.	`string`	no
`published`	Whether a post is published. Default is published.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

The other fields are taken from the metadata of the page URL given in the 'link' param.

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new link ID	`string`

If we have a large image available for your website, we will now show a larger (154x154px) image preview in any story that points to your site, this change excludes any link story pointing to an external video. These include:

Link Page post
Link Page post ad
Organic stories about people liking, commenting or sharing your Link Page post
Sponsored stories about people people liking, commenting or sharing your Link Page post
Organic stories about people sharing a link to your site
Sponsored stories about people sharing a link to your site (called Domain Sponsored Stories)

There are different ways to make sure you will get a large image preview in news feed desktop:

You can select the images that Facebook will crawl from your website when you're creating your Link Page post from the Page composer. If you select an image that is larger than 154x154px, then your Link Page post will have the large format.
If you do not see any large image for the offsite destination you want to promote, you need to add larger images to the Open Graph tags associated with your website: Open Graph tags are included in your page’s HTML and allow the Facebook Crawler to generate previews when your content is shared on Facebook. One of these tags is called "og:image": this is the image associated with your website page. If you give us an image that is 154X154px or larger, shares of your website page (in a Link Page post or any user story pointing to this website page) will be shown with the large format in news feed desktop.
Finally, you can also select a custom image for your Link Page post via Power Editor: if you specify a custom image that is larger than 154X154px, your Link Page post will have the larger format.

notes

Create

You can create a note on a Page by issuing an HTTP POST request to PAGE_ID/notes with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`subject`	The subject of the Note	`string`	yes
`message`	Note content	`string`	yes

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new note ID	`string`

photos

Create

You can post photos to a Page's Wall by issuing an HTTP POST request to PAGE_ID/photos with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`source`	Photo content	`multipart/form-data`	yes
`message`	Photo description	`string`	no
`targeting`	JSON object containing countries, cities, regions or locales Example: {'countries':['US','GB']}	`string` containing JSON object	no
`feed_targeting`	JSON object containing targeting parameters See [Feed Targeting](#targeting)	`string` containing JSON object	no
`published`	Whether a post is published. Default is published.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new photo ID	`string`

posts

Create

You can create a post on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters. Additionally, Page posts can also be scheduled to go live at a future time up to 6 months or can be created in an "unpublished" state where they are not visible on the pages timeline or in the page fan's news feeds. Unpublished posts can be used as Sponsored Stories.

Parameter	Description	Type	Required
`message`	Post message	`string`	either `message` or `link`
`link`	Post URL	`string`	either `message` or `link`
`picture`	Post thumbnail image (can only be used if `link` is specified)	`string`	no
`name`	Post name (can only be used if `link` is specified)	`string`	no
`caption`	Post caption (can only be used if `link` is specified)	`string`	no
`description`	Post description (can only be used if `link` is specified)	`string`	no
`actions`	Post actions	`array` of objects containing `name` and `link`	no
`targeting`	JSON object containing countries, cities, regions or locales Example: {'countries':['US','GB']}	`string` containing JSON object	no
`published`	Whether a post is published. Default is published. This field is `not` supported when actions parameter is specified.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new post ID	`string`

Questions

Create

You can post a question on behalf of the Page by issuing an HTTP POST request to PROFILE_ID/questions with the publish_stream permissions and the following parameters.

Parameter	Description	Type	Required
`question`	The text of the question	`string`	yes
`options`	Array of answer options	`array`	no
`allow_new_options`	Allows other users to add new options (True by default)	`boolean`	no
`published`	Whether a post is published. Default is published.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

Delete

You can delete a question by issuing an HTTP DELETE request to the QUESTION_ID object with the publish_stream permission.

milestones

Read

You can read milestones for a page by issuing an HTTP GET too /PAGE_ID/milestones with a Page Access Token. This will return the following fields.

Parameter	Description	Type
`id`	The ID of a milestone event	`string`
`title`	The title of the milestone	`string`
`from`	`JSON` object containing the name, category, and id of the Page	object
`description`	The description of the milestone	`string`
`created_time`	The creation time of the milestone	date/time format `ISO-8601`
`updated_time`	The update time of the milestone	date/time format `ISO-8601`
`start_time`	The start time of the milestone	date/time format `ISO-8601`
`end_time`	The end time of the milestone. Page's milestones have the same start and end time	date/time format `ISO-8601`

Create

You can add a milestone by issuing an HTTP POST request to PAGE_ID/milestones with a Page Access Token and the following parameters:

Parameter	Description	Type	Required
`title`	The title of the milestone	`string`	Y
`description`	The description of the milestone	`string`	Y
`start_time`	Th start time of the milestone. A Page's milestones have the same start and end time.	date/time format `ISO-8601`	Y

If the edit is successful, you get the following response:

Parameter	Description	Type
`id`	The ID of the milestone	`string`

Delete

You can delete a milestone by issuing an HTTP DELETE request to /milestone_id with a Page Access Token

If the delete is successful, you get the following return.

Description	Type
If the delete is successful	`boolean`

offers

Read

You can read offers of a Page by issuing an HTTP GET to /PAGE_ID/offers with a Page Access Token. This will return the following fields:

Name	Description	Type
`id`	The ID of the Offer	`string`
`from`	`JSON` object containing `name`, `category`, and `id` of the page that posted the Offer	`JSON` object
`title`	The title of the Offer	`string`
`created_time`	Time when the Offer was created	date/time format
`expiration_time`	The expiration time of the Offer (used when displaying the Offer)	date/time format `ISO-8601`
`terms`	The description of the terms under which the offer can be claimed	`string`
`image_url`	The URL of the image for the offer.	`string`
`claim_limit`	The maximum number of times the offer can be claimed	`integer`
`coupon_type`	The type of offer: `in_store_only`, `in_store_and_online` or `online_only`	`string`
`redemption_link`	The URL where the offer may be redeemed	`string`
`redemption_code`	A code to enter on your website to receive the discount or promotion	`string`

Create

You can create an Offer for a Page by issuing an HTTP POST to /PAGE_ID/offers with a Page Access Token and the following parameters:

To publish an Offer a corresponding ad must also be created and go live. The parameters `scheduled_publish_time` and `published` parameters are deprecated, and will be silently ignored.

Parameter	Description	Type	Required
`title`	The title of the Offer	`string`	Y
`expiration_time`	The expiration time of the Offer (used when displaying the Offer)	date/time format `ISO-8601`	Y
`terms`	The terms of the Offer	`string`	N
`image_url`	The URL for the Offer's image. Either `image_url` or `image` parameter should be specified, but not both.	`string`	N
`image`	The image for the Offer. Either `image_url` or `image` parameter should be specified, but not both.	`binary file`	N
`claim_limit`	The maximum number of times the offer can be claimed	`integer`	N
`coupon_type`	The type of offer: `in_store_only`, `in_store_and_online` or `online_only`	`string`	N
`qrcode`	QR code - alphanumeric with limited punctuation: $ % * + - . / :	`string`	N
`barcode`	12-character UPC-A or 13-character EAN-13 barcode (alphanumeric)	`string`	N
`redemption_link`	The URL where the offer may be redeemed	`string`	N
`redemption_code`	A code to enter on your website to receive the discount or promotion (50 characters max)	`string`	N

If successfully created, you will receive the following response:

Description	Description	Type
`id`	The ID of the Offer	`string`

Offers will remain unpublished until a corresponding ad is live on the site. To publish an offer please create an ad to go live at the time you would like to publish the offer.

Delete

You can delete a Offer by issuing an HTTP DELETE request to /offer_id with a Page Access Token.

If the delete is successful, you get the following return.

Description	Type
If the delete is successful	`boolean`

Note that you cannot modify an offer.

Messages

Read

You can read the messages for a page by issuing an HTTP GET request to /PAGE_ID/conversations with a Page Access Token and read_page_mailboxes permission. This will return the following fields:

Name	Description	Type
`id`	The ID of a conversation, e.g., `t_id.216477638451347`	`string`
`snippet`	The title of a message in the conversation	`string`
`updated_time`	Last update time of the conversation	date/time format `ISO-8601`
`message_count`	The number of messages in the conversation	`integer`
`unread_count`	The number of unread messages in the conversation	`integer`
`tags`	A Set of tags indicating the message folder, and whether the conversation is read and seen.	`JSON` objects that include a name field.
`participants`	Users who are on this message conversation	`JSON` array of objects containing `name`, `email`, and `id` for each participant.
`senders`	Users who send a message on the conversation	`JSON` array of objects containing `name`, `email`, and `id` for each participant who sent a message
`can_reply`	Whether The Page can reply to the conversation	`boolean`
`is_subscribed`	Whether you are subscribed to the conversation	`boolean`
`messages`	List of all messages in the conversation	`JSON` array of `message` objects. Each `message` object contains `id`, `created_time`, `tags`, `from`, `to`, and `message` fields. A message ID look like `m_id.388262297854964`.

Reply

Note that a page can only reply to a user's message. It cannot initiate a private message with a user. Also, a page can respond not more than twice to a user's message before the user has replied back.

You can reply to a user's message by issuing an HTTP POST to /CONVERSATION_ID/messages with the following parameters. A conversation ID look like t_id.216477638451347.

Parameter	Description	Type	Required
`message`	The body of reply	`string`	Y

If the reply is successful, you get following response.

Description	Description	Type
`id`	The ID of the reply message, e.g., `m_id.325810694131945`	`string`

settings

Update

You can change whether users can post to the Wall of a page by issuing a POST request to PAGE_ID/settings with the manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`setting`	Which single setting to update: `USERS_CAN_POST`, `USERS_CAN_POST_PHOTOS`, `USERS_CAN_TAG_PHOTOS`, `USERS_CAN_POST_VIDEOS`	`string`	Y
`value`	`true` or `false`	`boolean`	Y

If the setting has been changed successfully you will get the following return:

Description	Type
If the setting was successfully set or changed	`boolean`

statuses

Create

You can post a status message on a Page by issuing an HTTP POST request to PAGE_ID/feed with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`message`	Status Message content	`string`	yes
`published`	Whether a post is published. Default is published.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new status message ID	`string`

videos

Create

You can publish a video on a Page by issuing an HTTP POST request to https://graph-video.facebook.com/PAGE_ID/videos with the publish_stream and manage_pages permissions and the following parameters.

Parameter	Description	Type	Required
`source`	Video content	`multipart/form-data`	yes
`title`	Video title	`string`	no
`description`	Video description	`string`	no
`published`	Whether a post is published. Default is published.	`boolean`	no
`scheduled_publish_time`	Time when the page post should go live, this should be between 10 mins and 6 months from the time of publishing the post.	UNIX `timestamp`	no

If the create is successful, you get the following return.

Name	Description	Type
`id`	The new video ID	`string`

tabs

Read

You can read the tabs for a Page by issuing an HTTP GET to /PAGE_ID/tabs with a Page Access Token. This will return the following fields.

Name	Description	Type
`id`	ID of the tab	`string`
`name`	Name of the tab	`string`
`link`	Link to the tab on Facebook	`string` containing the tab's URL
`application`	The `Application` providing the tab	object containing `id` and `name`
`custom_name`	The custom name of the tab. If this is not set, the name of the tab will be determined by the application.	`string`
`is_permanent`	Whether or not the tab is permanently installed	`boolean`
`position`	The order in which the tab appears on the `Page`'s profile	`integer`
`is_non_connection_landing_tab`	Whether this is the default landing tab for users who have not liked and are not admins of this `Page`	`boolean`

You can also retrieve certain specific tabs by issuing an HTTP GET to /TAB_ID.

Testing App Installs

You can test if a specific app is installed on a page profile tab by issuing an HTTP GET to PAGE_ID/tabs/APP_ID. If the app is installed, this will return the following fields.

Name	Description	Type
`id`	ID of the application tab	`string`
`name`	Name of the tab	`string`
`link`	Link to the tab on Facebook	`string` containing the tab's URL
`application`	The `Application` providing the tab	object containing `id` and `name`
`position`	The order in which the tab appears on the `Page`'s profile	`integer`

This request will work for any APP_ID and return the above fields is the app is installed on the page. If the app is not installed on the page, this request will return an empty data[] array.

You can also issue this same query with an app access token. In this case, you can query any PAGE_ID, and the above fields will be returned if your app is installed on the specified page. An empty data[] array is returned as usual if the app is not installed on the specified page.

Create

You can install a profile_tab at the end of the current list of installed tabs for a page by issuing an HTTP POST request to PAGE_ID/tabs with a Page Access Token:

Parameter	Description	Type	Required
`app_id`	ID of the application for which to install the tab.	`string`	Y

If the create is successful, you get the following return:

Description	Type
If the create succeeded	`boolean`

Update

You can update an installed profile_tab for a page by issuing an HTTP POST request to /PAGE_ID/tabs/TAB_ID with Page Access Token and the following parameters:

Parameter	Description	Type	Required
`position`	Order in which the tab will appear on the profile. Must be after permanent tabs and less than the number of installed tabs. Index starts at 0	`integer`	N
`custom_name`	Name to be used for the tab. If this is set to an empty string, the tab will use the application’s default tab name.	`string`	N
`is_non_connection_landing_tab`	Set this tab as the default landing tab for users who have not liked and are not admins of the Page. If provided, value must be `true`.	`boolean`	N
`custom_image_url`	URL for an image to be used as a custom icon for this Page app. Note that either `custom_image_url` or `custom_image` can be set, but not both.	`string`	N
`custom_image`	The name of an image file to be used as a custom icon for this Page app. Note that either `custom_image_url` or `custom_image` can be set, but not both.	`image file`	N

If the edit is successful, you get the following return.

Description	Type
If the edit succeeded	`boolean`

Delete

You can delete an installed profile_tab where is_permanent is not true for a page by issuing an HTTP DELETE request to /PAGE_ID/tabs/TAB_ID object with a Page Access Token.

If the delete is successful, you get the following return.

Description	Type
If the delete is successful	`boolean`

admins

Belongs

To check if a specific user is an admin of the Page, issue an HTTP GET request with the appropriate PAGE_ID, Page Access Token, and USER_ID to https://graph.facebook.com/PAGE_ID/admins/USER_ID

This returns an array of objects with the following fields:

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

blocked

Read

You can get a list of users blocked for a page by issuing an HTTP GET request to PAGE_ID/blocked/ with the page admin access_token. This returns an array of objects with the following fields:

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

Belongs

You can check if a user is blocked for a page by issuing an HTTP GET request to PAGE_ID/blocked/USER_ID with the page admin access_token.

If the user is not blocked from the page, a blank object will be returned. Otherwise, an object with the following fields will be returned.

Name	Description	Type
`id`	ID of the user	`string`
`name`	Name of the user	`string`

Create

You can block a user from posting content to your page by issuing an HTTP POST request to PAGE_ID/blocked with the the page admin access_token with the following parameters:

Parameter	Description	Type	Required
`uid`	Comma-separated list of the user IDs you wish to block	`string`	yes

This returns an array where the keys are the user IDs (string) and the values a boolean of whether or not the block was successful.

Delete

You can unblock a blocked user for your page by issuing an HTTP DELETE request to PAGE_ID/blocked with the page admin access_token with the following parameters:

Parameter	Description	Type	Required
`uid`	ID of the user you wish to unblock	`string`	yes

If the delete is successful, you get the following return.

Description	Type
If the delete is successful	`boolean`

Targeting Page Posts

News feed targeting for Pages is a feature that allows Pages to target fans in the newsfeed. The new feature is designed to help Pages reach fans in their news feed with engaging and relevant content.

Page post targeting allows a Page to choose the posts and target those posts to groups of fans based on a variety of demographic criteria. For example, a Page can choose to target a post about the weather in San Francisco to fans residing in San Francisco, Ca.

At this time Page posts can be targeted on the following criteria:

Age
Gender
Relationship Status (“Interested In” in the Advertising create Flow)
Language
Education
College Grad (college name, major year)
In high school
Workplace
Geographic Location
Country
State
City

'''Note''' the above targeting respects any privacy gating on the Page. For example, if you gate your page to ages 21+ for alcohol, you cannot target any users under 21 as those eligible to see your post must be a Fan. The current page post API is described here: https://developers.facebook.com/docs/reference/api/page/#posts

We are adding the following parameters as part of the “feed_targeting” parameter:

Parameter	Description	Type
genders	1: Male 2: Female Default: All	Int
age_max	Maximum age	Int
age_min	Must be 13 or higher. Default is 0	Int
countries	Values of targeting countries. You can specify up to 25 countries. List of countries can be obtained through the same interface as targeting for Ads Autocomplete Data.	array
regions	Values of targeting regions. List of regions can be obtained through the same interface as targeting for Ads Autocomplete Data.	array
cities	Values of targeting cities. List of cities can be obtained through the same interface as targeting for Ads Autocomplete Data.	array
relationship_statuses	Array of integers for targeting based on relationship status. Use 1 for SINGLE, 2 for IN_RELATIONSHIP, 3 for MARRIED, and 4 for ENGAGED. The default of ALL is used if you specify Null. The default of ALL is also used if you do not specify the field. Do not specify zero.	array
interested_in	Indicates targeting based on the "interested in" field of the user profile. You can specify an integer of 1 to indicate MALE (for example, if you specify "interested_in":[1]). An integer of 2 indicates FEMALE. The default of ALL is used if you specify Null. The default of ALL is also used if you do not specify the field. Do not specify zero. Please note "interested in" targeting is not available in France due to local laws.	array
locales	Locales. To get the available values, see Retrieving Autocomplete Data. Alternatively, if you use the Autocomplete file (referenced above), the values are specified as indices; the indices are in a sub-array called 'locales'. Uses of this parameter include for targeting users with a different language than the common language for the specified location parameter; you specify an ID for the language, e.g. 5 for German. Limit: 50 locales.	array
education_statuses	Array of integers for targeting based on education level. Use 1 for HIGH_SCHOOL, 2 for UNDERGRAD, and 3 for ALUM. For one ad group, you can specify only one value. The education_statuses parameter is required if you specify the college_majors parameter.	array
work_networks	Company, organization, or other workplace. Must be supplied as the id name pair e.g. [{"id":"50431654","name":"Microsoft"}. See Retrieving Autocomplete Data] Limit: 200 work networks.	array
college_networks	Colleges, for college graduates. Limit: 200 college networks. See Retrieving Autocomplete Data	array
college_majors	Array of strings for specific college majors. Requires that you also specify a value for the education_statuses parameter. Limit: 200 college majors. See Retrieving Autocomplete Data	array
college_years	Array of integers for graduation year from college.	array

Examples

Targeting fans in the US

 curl -F "message=test message US"\ 
      -F "feed_targeting={'countries':['US']}"\
 "https://graph.facebook.com/377995692249413/feed?access_token=PAGE_ACCESS_TOKEN"

Response {"id": "377995692249413_378470615535254"}

Target fans in UK

 curl -F "message=test message GB"\ 
      -F "feed_targeting={'countries':['GB']}"\
 "https://graph.facebook.com/377995692249413/feed?access_token=PAGE_ACCESS_TOKEN"

Response

 {"id": "377995692249413_378471455535170"}

Targeting 18-21 year-old males in the US who are married

 curl -F "message=test message US"\ 
      -F "feed_targeting={\
           'countries':['US'],\
           'genders':[1],\
           'relationship_statuses':[3],\
           'age_min':'18',\
           'age_max':'21'}\
 "https://graph.facebook.com/377995692249413/feed?access_token=PAGE_ACCESS_TOKEN"

Response

 {"id": "377995692249413_378472548868394"}

Other Considerations

Reading the targeting information

The targeting information for a post can be read by querying for the "feed_targeting" parameter as in the example below:

 curl https://graph.facebook.com/377995692249413_397606830288299?access_token=$PAGE_TOKEN\
      &pretty=true\
      &fields=feed_targeting

Response

 {
    "feed_targeting": {
       "country": "[\"US\"]",
       "age_min": 18,
       "age_max": 21,
       "genders": [
          1
       ],
       "relationship_statuses": [
          "4"
       ]
    },
    "id": "377995692249413_397606830288299",
    "created_time": "2012-08-01T00:53:52+0000"
 }

Gating vs. Targeting

Gating a post is restricted to only language and country currently. This is different from news feed targeting because a gated post to a language or country will not show up to a user outside of the gating criteria. Using targeting, the post will be visible on the Page and only visible to those in the targeting segment of the Page. If a user shares a post, the user’s friends will be able to see the post even if they are outside the targeting set.

How-Tos

How to: Publish to a Page

How to upload a video to an Application, Group, or Page's wall using Graph API

Updated about a week ago

Objects

Introduction to Pages via the Graph API

Example

Fields

Connections

Realtime Updates

Adding an App to Get Realtime Updates

Deleting an App

Examples

Feed Example: Like

Feed Example: Comment

Feed Example: Post

Page Access Tokens

Page Admin Roles

Updating Page Attributes

Setting a Page Profile Photo

Setting a Cover Photo

Hiding a Page Post

Unpublished / Scheduled Page Posts

feed

Types of Page Posts

events

Create

Edit

Delete

links

Create

notes

Create

photos

Create

posts

Create

Questions

Create

Delete

milestones

Read

Create

Delete

offers

Read

Create

Delete

Messages

Read

Reply

settings

Update

statuses

Create

videos

Create

tabs

Read

Create

Update

Delete

admins

Belongs

blocked

Read

Belongs

Create

Delete

Targeting Page Posts

Examples

Other Considerations

Reading the targeting information

Gating vs. Targeting

How-Tos