New Page APIs

Recently, we announced the launch of the new Pages at fMC, and today we want you to know about new APIs for Pages. These APIs allow you to do the following operations:

• Manage a Page's milestones
• Manage a Page's messages
• Edit a Page's attributes and About section
• Set a custom Page apps image
• Hide (or unhide) a Page post

This post introduces these APIs and links to relevant sections in developer docs for further reading.

All these APIs require a valid Page Access Token with manage_pagespermission.

Milestone APIs

Businesses can add a milestone to their Page. A Pages' milestone always has the same start and end time.

Reading Milestones

You can read a Page's milestones by issuing an HTTP GET request like below:

curl https://graph.facebook.com/PAGE_ID/milestones?access_token=_

Here is an an example of how a response looks:

{
  "id": "317497264976561",
  "from": {
    "name": "Sample Page",
    "category": "Club",
    "id": "2434449890484"
  },
  "created_time": "2012-03-12T21:33:23+0000",
  "updated_time": "2012-03-12T21:33:23+0000",
  "start_time": "2010-02-16T18:37:23+0000",
  "end_time": "2010-02-16T18:37:23+0000",
  "title": "A New Milestone",
  "description": "Milestone Description"
},
  ...
  ], 
  "paging": {
    "next": "https://graph.facebook.com/243444989048456/milestones?
    format=json&limit=5000&offset=5000&__after_id=301163799943241"
  }
}

You can also use FQL table page_milestone for reading a Page's milestones:

SELECT id, title, description FROM page_milestone WHERE owner = PAGE_ID

Creating a Milestone

You can create a milestone for a Page by issuing an HTTP POST request with title, description, and start_time parameters:

curl -F "title=Example Title" -F "description=Description" \
-F "start_time=1329417443" \
"https://graph.facebook.com/PAGE_ID/milestones?access_token=_"

If the call is successful, it will return the ID of the new milestone:

{"id":"302062153186739"}

Deleting a Milestone

You can also delete a Page's milestone by issuing an HTTP DELETE request:

curl -XDELETE http://graph.facebook.com/MILESTONE_ID?access_token=__

If the call is successful, it will return true.

Editing a Page's Attributes

This new API allows you to edit your Page's basic information (phone number, address, description, website URL, and cover photo) or the About section.

You can edit your Page's attributes by issuing an HTTP POST request:

curl -F "about=About Text" -F "phone=415-448-4444" \
-F "description=Description" -F "general_info=Info" -F \
-F "website=http://example.com" \
"https://graph.facebook.com/PAGE_ID?access_token=__" 

If the call is successful, it returns true.

Also, you can set your Page's cover photo by issuing an HTTP POST request:

curl -F "cover=1232343" -F "offset_y=30" -F "no_feed_story=false" \
"https://graph.facebook.com/PAGE_ID?access_token__"

You can read your Page's cover photo using either page FQL table or Graph API Page object end point:

SELECT pic_cover from page where page_id = PAGE_ID

Page App APIs

Reading Page Apps

In addition to Graph API call, you can use FQL table profile_view for reading existing third-party apps for a Page.

SELECT name, link FROM profile_view WHERE profile_id = PAGE_ID

Updating a Page App's Image You can set an icon for a Page app by issuing an HTTP POST request like below. See Page's API documentation.

curl -F "custom_image_url=http://example.com/image.jpg" \
https://graph.facebook.com/PAGE_ID/tabs/app_<APP_ID>?access_token=_"

Alternatively, you can upload an image file with custom_image parameter:

curl -F "custom_image=@tab_image.png" \
https://graph.facebook.com/PAGE_ID/tabs/app_<APP_ID>?access_token=_

Note that a Page App image size should be 111x74 pixels.

Messages APIs

Messaging APIs allows you to read private messages sent to the Page and reply to them privately as the Page. You can't reply to someone more than twice until they responds back to you. People initiate the conversation with a Page and until someone has messaged you, you can’t message them. Using this API requires read_mailbox permission in addition to manage_pagepermission.

Reading Messages

You can read a Page's messages by issuing an HTTP GET request:

curl https://graph.facebook.com/PAGE_ID/conversations?access_token=_

Replying To a Message

You can reply to a user's message by issuing an HTTP POST request:

curl  -F "message=A Reply" \
"https://graph.facebook.com/THREAD_ID/messages?access_token=__"

A thread ID looks like t_id.21647763845134.

If the call is successful, it will return the ID of the new message.

{"id":"m_id.325810694131945"}

Page Post Visibility APIs

To hide a Page post, you can issue an HTTP POST request. See Page's API documentation.

curl –F 'is_hidden=true" \
"https://graph.facebook.com/<POST_ID>?access_token=_"

To make a hidden Page post visible, set is_hidden to false.

We are excited to see how developers use these new APIs.