Version 2.9

Graph API | Marketing API

Graph API

Released April 18, 2017 | Available until July 18, 2019

• New Features
• Changes
• Deprecations
• 90-Day Breaking Changes

New Features

• General
• Pages
• Permissions
• Places Graph
• Video APIs
• Webhooks

General

• Read After Write - Graph API POST requests now support returning specified values of an object during the same request as a write, saving a round trip for clients. If a fields parameter is specified (explanation of the syntax), the request will first do the write, then read the created or updated object, selecting fields using the fields parameter, as the response. Read-after-write is now enabled for all versions of the Graph API. Visit our docs page to learn more.

• New short_names Field on the User Object - The following field has been added to the user endpoint:

  • short_name - first_name assumes the universally friendly way to refer to a person is by their first name. However, in many cultures (especially Chinese, Japanese, Korean, Thai, Indic, and a few others), it's inappropriate to address people by their first name. The new short_name method understands the culture-specific rules for how to address a person with a short name. So, for a viewer in the US, they'll continue to see friends in China, Japan, Korea, and India addressed by their first name, but their friends in East and South Asia will see friends with full names.

Pages

• Business App Page Mapping - The user node has two new edges, ids_for_pages and ids_for_apps, for de-referencing a person's ID for an app or a page. The ids_for_pages edge returns other IDs that person has for pages owned by the same business. Similarly, the ids_for_apps edge returns other IDs that person has for apps owned by the same business. See Connecting with People Across Apps and Bots in Messenger.

• Page POST Support to Add Pages to Crosspost Videos - Approve and accept a crossposting relationships request from another page by POST /{page_id}/crossposting_pages.

• Webhooks IDs Are Serialized as Strings - Numeric IDs are converted to strings in this webhooks update.

Permissions

• Granular Permissions - This new feature gives people more control over managed object permissions. During the login step, if a permission related to pages, business, or groups is granted, the user will have the option to select which managed objects the permission applies to. This means that you might see fewer pages, businesses and groups. Users can manage the following permissions at a granular level:

  • business_management
  • manage_pages
  • pages_manage_cta
  • pages_manage_instant_articles
  • pages_messaging
  • pages_messaging_payments
  • pages_messaging_phone_number
  • pages_messaging_subscriptions
  • pages_show_list
  • publish_pages
  • read_page_mailboxes
  • user_managed_groups

Places Graph

• Current Place - The following fields have been added:

  • GET /current_place/results - Helps determine what place a person is currently at by using location signals. User permission is required.
  • POST /current_place/feedback - Allows you to provide feedback about whether they were actually there. For more information, see Places Graph

• GET /search?type=place - The following parameters have been added:

  • categories - Search by category.
  • matched_categories - Indicate which categories the resulting place matches. Must be used with categories.

Video APIs

• Time Spent in Video Metrics for Page - The following metrics have been added. For more information, see Insights Metric /{object-id}/insights/{metric}.

  • page_video_view_time- The time spent on videos on the page.
  • post_video_view_time_by_country_id - The time spent on videos on the page by country.

Webhooks

• Apps Can Receive Changed Values for User's Profile Updates with Webhooks Updates - When a user changes a field, your app can receive the new value as part of the update, saving the step of checking the value. Previously, whenever a user changed one of their fields, we would notify the app of the field that changed without sending the new value.

• Documentation - Webhooks now has reference documentation for topics and fields you can subscribe to. This documentation is on Facebook Developers site under Webhooks Reference in the Graph API.

• Sample Sender Tool - The new tool makes it easier for developers to test out the Webhooks update structure before subscribing to the topic. In the past, developers had to subscribe to a field and then try to trigger the update by making a change through Facebook. For example, an app might need to know when a user (users that installed the app and granted needed permissions) changes their profile picture. The app would subscribe to the profile picture field in the Webhooks framework. However, to test how this works, you had to change the profile picture on some user that had installed the app to see the structure of the update we send. The sample sender tool allows apps to test the update structure without having to make an unnecessary change. You can find the sample sender tool in the webhooks section of your app's dashboard.

• Versioning - Webhooks versions are now the same as Graph API. Any existing Webhooks subscriptions will be running on the oldest supported version of the app. Previously, Webhooks subscriptions didn't support versioning. The only way to make changes was by making breaking changes. For more information on Webhooks versions, see Versioning.

Changes

• General
• Pages
• Posts
• Videos API
• Webhooks

General

• The Batch API returns an error rather than a null response for aborted request items in the Batch API. For more information, see Graph API, Making Batch Requests.

• GET /{url}/share - The share endpoint has been removed and replaced with:

  • engagement field with subfields:
    • comment_count
    • comment_plugin_count
    • reaction_count
    • share_count

Pages

• /{page-id}/feed - Backdated posts are included in the {page_id}/feed request if the backdated_time of the post is within the since and until time range. The created_time is the actual creation time. (See changes to Posts below.)

• page-restaurant-services - All fields now return false or true instead of 0 or 1.

• overall_star_rating — If there are 0 or a small number of ratings, the overall_star_rating field will not be returned.

• GET /{post-id} - The following field has been added to this endpoint:
  • promotable_id - Previously, certain posts could not be promoted, only their contents. In such cases, the id field would return the contents ID, rather than the ID for the post. Posts now always return their own ID in the id field, and a new field, promotable_id, is added to the GET {post-id} endpoint to be used when promoting the post.

Posts

• Backdating a post will no longer update the post's created_time value. Instead, it will duplicate the original, but with created_time and backdated_time set to the new value. The original post will keep its old created_time value and gain the new backdated_time and value. Finally, GET {post-id}/feed will no longer return the original post, but instead will return the newly created duplicate.

Video API

• Expose dash preview URL for live video instead of RTMP URL.

• GET /{page_id}/crosspost_pending_approval_pages - List all the Pages your Page has sent crossposting requests, but that have not accepted yet.

• GET /{page_id}/crosspost_whitelisted_pages - List all the pages you have given crossposting permission.

• POST /{video_id}/allow_crossposting_for_pages = [{"page_id": {page_id}, "allow": {true/false}] - Allow or disallow the permission for certain Pages in your crossposting allow list to crosspost a specific video.

• POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "EXPIRE_ALL_CROSSPOSTS_ON_SHARED_ASSETS"}] - Remove pages from your crossposting allow list and expire all previously crossposted content.

• POST /{page_id}/crossposting_pages=[{"page_id": {page_id}, "allow": false, "action": "NO_ACTION"}] - Remove pages from your crossposting allow list without affecting previously crossposted content.

Webhooks

• GET /{app-id}/subscriptions - This endpoint now returns versions for fields. Before Webhooks versioning was introduced, the endpoint returned only a list of subscribed fields. Now the endpoints return the list of fields with their respective versions.

Deprecations

• Messages

Messages

• GET /{message-id} - The following field has been deprecated:
  • subject

• GET /{thread-id} - The following field has been deprecated:
  • tags

90-Day Breaking Changes

• Links
• Video
• Webhooks

Links

• The following fields are deprecated for edges and dialogs that allow attaching links to posts:

  • caption
  • description
  • name
  • picture
  • thumbnail

• The edges and dialogs for which these are deprecated include:

  • POST /{event-id}/feed
  • POST /{group-id}/feed
  • POST /{page-id}/feed
  • POST /{user-id}/feed
  • share and feed dialogs

Video

• Insights Edge - All paid and organic metrics are deprecated.

Webhooks

• The following Webhooks fields from the user topic are deprecated:

  • about_me
  • birthday_date
  • contact_email
  • current_location
  • education_history
  • hometown_location
  • sex
  • statuses
  • tv
  • work_history

• Instead use:

  • about
  • birthday
  • education
  • email
  • gender
  • hometown
  • location
  • status
  • television
  • work