Facebook Platform Changelog

This changelog covers what's changed in Facebook's APIs. These changes include Facebook's server-side APIs, Facebook SDK for JavaScript, dialogs and other services.

The most recent version of the API is Version 2.8, which was introduced on October 5th, 2016.

To learn more about versions, please see our overview of how versions work. For more info on upgrading, including code samples, please see our expanded upgrade guide.


API Upgrade Tool

The API Upgrade Tool shows which of your app's API calls may be affected by changes in newer versions of the API. You'll be able to quickly see which changes you need to make to upgrade from your current version to a newer version.

Go To API Upgrade Tool

Related Topics

Versions

Version Path Date Introduced Available Until

v2.8

/v2.8/{object}

October 5th, 2016

At least October 2018

v2.7

/v2.7/{object}

July 13, 2016

October 5, 2018

v2.6

/v2.6/{object}

April 12, 2016

July 13, 2018

v2.5

/v2.5/{object}

October 7, 2015

April 12, 2018

v2.4

/v2.4/{object}

July 8, 2015

October 7, 2017

v2.3

/v2.3/{object}

March 25, 2015

July 8, 2017

v2.2

/v2.2/{object}

October 30, 2014

March 25, 2017

v2.1

/v2.1/{object}

August 7, 2014

October 30, 2016

v2.0

/v2.0/{object}

April 30, 2014

Unavailable as of August 7, 2016

v1.0

/{object}

April 21, 2010

Unavailable as of April 30, 2015


Marketing API

Version Path Date Introduced Available Until

v2.8

/v2.8/{object}

October 5th, 2016

v2.7

/v2.7/{object}

July 13, 2016

April 2017

v2.6

/v2.6/{object}

Apr 12, 2016

Oct 5, 2016

v2.5

/v2.5/{object}

Oct 7, 2015

July 13, 2016

v2.4

/v2.4/{object}

July 8, 2015

April 11, 2016

Nov 17th, 2016

Deprecations

  • The Graph API behavior of POST and DELETE to {object-id}/likes has changed to only be accessible for Page Access Tokens. You can read more about this in our docs.

October 5th, 2016 - API Version 2.8

New Features in v2.8

  • New Common Open Graph Actions - Facebook has added two new common Open Graph action types that are available to all developers in all versions of the API: games.plays and books.rates.
  • ThreatExchange - ThreatExchange has some new features, including support for Webhooks and new tagging functionality. Please see the ThreatExchange Changelog for more information.
  • New Resumable Upload API - Facebook now offers a new way to upload files a small piece at a time, allowing for more reliability over poor connections. Please see our guide on the Resumable Upload API for more information. This API is only available for page thumbnails right now, but will expand to other types of media in the future (like video.)

Changes from v2.7 to v2.8

  • Feed Targeting - The targeting and feed_targeting fields on the /page/feed edge now consistently use geo_locations instead of specifying geography via other methods. Also see our guide on targeting which includes information about the geo_locations object.

Deprecations in v2.8

  • Groups - The /admined_groups edge on the User node has been deprecated. Use groups edge on the User node instead.
  • User Bios - The bio field on the User object is no longer available. If the bio field was set for a person, the value will now be appended to the about field.
  • Deprecation of Custom Open Graph Actions - v2.8 no longer allows apps to create new Open Graph action types or object types or publish open graph stories that use custom action or object types. Approximately 90 days after the v2.8 release, no versions of the API will allow the creation of new Open Graph action or object types. Additionally, all App Collections will be removed from people's profiles at that time. Approximately 1 year after the v2.8 release, no version of the API will allow publishing stories that use custom action or object types. Please see our deprecation guide for more information.

Marketing API Changes in v2.8

New Features

  • Instant Articles is now a separate ads placement, so that advertisers can enable or disable showing ads in Instant Articles. This new placement options is under /ACCOUNT_ID/adsets and /AD_SET_ID. See Targeting Specs. If you use this placement you must also select `feed` as a position and for `device_platforms` select `mobile` since Instant Articles is for mobile only.
  • Facebook Offers is redesigned and is easier for people to save and redeem your offer from any device. If they don't use your offer, they'll get notifications about it before it expires. To use the API to create offers:
    • Use /nativeoffers as an endpoint. The endpoint /offers is associated with the old product and has been deprecated.
    • Use offer_id in the promoted_object for an ad set.

Breaking Changes

Ads Management

  • As of 2.8, Website Custom Audiences now only allow at most 200 comparisons in the rule. The number of comparisons are the number of comparison operators in the rule.

The following rule contains 3 comparisons:

{
  "or": [
    {
      "url": {
        "i_contains": "shoes"
      }
    },
    {
      "and": [
        {
          "event": {
            "eq":"ViewContent"
          }
        },
        {
          "price": {
            "gte": 100
          }
        }
      ]
    }
  ]
}
  
  • The place_page_set_id field under Ad creative is now optional for versions v2.7 and v2.6
    and has been deprecated in v2.8. See Ad Creative.
  • offer_data under 'link_data' for an ad object has been deprecated.
  • The ad account group endpoints AdAccountGroup have been deprecated. To manage Ad Accounts, you should use Business Manager or Business Manager API with business_management extended permission, see Business Manager API, Overview.
  • The edge AD_ACCOUNT/audiences has been deprecated.
  • The ad_object_by_url field for /search in Ad Targeting Search has been deprecated.
  • The fields actor_id, actor_image_hash, actor_image_url, and actor_name have been deprecated from ad creative GET.

Ads Insights

  • We deprecated the redundant fields and parameters in /insights endpoint.
    In earlier releases it supported the params: fields,summary, default_summary, filtering and sort. However /insights should always exactly return what you queried in the POST requests.
  • In earlier releases we will display all valid fields for /insights if you provided an invalid field as a parameter. We now send an the error message which points to a list of valid fields.
  • In the past we inconsistently returned /insights fields in a variety of types: some fields were string such as impressions, some were numericstring, and some were floats. We now return all numeric fields, including floats as numericstring. All floating point numbers will maintain six precision points.
  • The insights metric post_like in the actions field is now named post_reaction, see Ads Action Stats, Reference. This is more consistent with naming in user interfaces.

Business Manager

The owner_business field has been deprecated and no longer exists for objects connected to a business, including Ad accounts, Ad Campaign, Product Catalog, and Instagram User.

July 13, 2016 - API version 2.7

New Features in v2.7

Pages

  • New Metrics for Pages We now include new metrics for Pages on follow/unfollow counts for Pages, with breakdowns by organic/paid, source, and time. We also include lifetime breakdown by user demographic info.

  • New Webhooks Field A new field is_webhooks_subscribed will now return the status of a Webhooks subscription from the Page node. This field can be retrieved via GET or updated with a POST on {page-id}.

Videos

  • Geotargeting Support We now support geotargeting and gating via the targeting param on POST {video-id} and POST {page-id}/live_videos. This can also be extended to supporting restrictions by excluded locales through the API.

  • New Fields There are two new fields on the Video node: feed_type and copyright_monitoring_status.

Changes from v2.6 to v2.7

Permissions

  • Business Manager API Permissions: To use the Business Manager API with API version 2.7 your app needs the business_management extended permission. You cannot use the ads_management or the manage_pages permissions to call Business Management API starting with 2.7. Facebook will migrate existing apps with these permissions to the new permission. Apps using this permission for the first time need to go through review, see Permissions and Business Manager API, Prerequisites.

Pages

  • Tagged Page Changes In v2.7, the GET {page-id}/tagged edge will now return posts that the Page has been tagged in. This is a change in behavior from previous versions that only returned posts directed to the Page.

  • Page Insights Change Page metrics insights must now be explicitly specified when making Page Insights related requests. The default behavior of returning all metrics when none are specified is no longer supported.

Marketing

  • Adaccount POST: AD_ACCOUNT_ID/adaccount POST is deprecated in 2.7. To update an account make a POST request to /adaccount directly.

  • New Daily Budget Logic: We changed the logic around ads delivery which impacts the interpretation of the daily ad budget limits. Starting with v2.7, you may be charged up to 125% of your daily budget on certain days. For example, if your daily budget is $10.00, you may be charged up to $12.50. However, your weekly spend will NOT exceed 7 times the daily amount, or $70.00 in this example. We will prorate this for partial weeks. Learn more in our documentation for the Ad Set Budget. Starting with v2.7, an ad set with a daily_budget cannot be updated to have lifetime_budget later, and vice versa.

  • Ad Placements Update: We have made improvements to our design of placement, so that advertisers can more easily identify and select placement options that will serve them best. Instead of having page_types as the only dimension, advertisers can select placements across different dimensions, such as device type including desktop or mobile, publisher such as facebook, instagram, or audience_network, and placements of each publisher. Only Facebook has multiple placements currently. The field page_types will still be included in read results, but cannot be used to create or update placements in v2.7. More details in Targeting Spec.

  • Insights Placement Updates: As a related change, on the /insights endpoints, we've introduced two new breakdowns options: publisher_platform and platform_position. Along with the existing impression_device breakdown, you can get performance metrics with these placement dimensions. See Insights Breakdowns for more details.

  • Ad Creative Update: With 2.7 object_story_id will be null for an ad creative created with an object_story_spec. The effective_object_story_id will always be the object_story_id regardless of object_story_spec. More details in Ad Creative.

  • Insights Integer Field: For Insights API, integer values were too big and overflowed with int32. We changed all int32 field values into numeric strings to keep them consistent with other Marketing API fields with currency values. With v2.7, numeric values in int32 are quoted in responses. In v2.5 for backwards compatibility, numeric values in int32 will be shown as a number. More details in our Ads Insights documentation.

Deprecations in v2.7

  • Open Graph URL Field In v2.7, the url field has been removed from the GET {open-graph-object-id} API.

90-day changes

  • Open Graph URL Field The url field will be removed from the GET {open-graph-object-id} API in all API versions.

April 12th, 2016 - API version 2.6

New Features in v2.6

Permissions

  • Pages Messaging - You can now request the pages_messaging permission to send and receive messages on behalf of a Page.
  • Send Page Messages By Phone Number - You can now request the pages_messaging_phone_number permission to send messages on behalf of Pages, using a phone number as an ID.

Pages

  • Notes on Users - We've added a new API which allow Page admins to take notes on Users. Please see the admin_notes edge on the Page node for more information.
  • Labels on Users - We've added a new API which allows Page admins to create labels for Users. Please see the labels edge on the User node for more information.
  • Send Messages to Users Using Page-Scoped ID or Phone Number - Pages can now send text, attachments, and template messages to users through their page-scoped-ids or phone numbers.

Video APIs

  • Live API - We're added an API to post and manage Live Videos. Access to these endpoints requires approval. Please see our Live API documentation for more information.

  • Live API Status - The Video node has a new field called live_status. This field will tell you the current broadcast state of the video. Values include: LIVE, LIVE_STOPPED, VOD. If this field is null, it means the video was never broadcasted. Please see the 'live_status' field in the Video node for more details

  • Live API Viewer Counts - The Video node has a new field called live_audience_count that tells you the number of unique viewers who watched the video when it was live.
  • Rights Manager API - We've introduced a new Rights Manager API that allows a copyright owner to claim ownership for videos and manage copyright matching rules. To use the API, please enroll via the Rights Manager Enrollment website. Please see our documentation for the Rights Manager API for more information about the API and the enrollment process.
  • Crossposted Videos - Pages can now create posts from videos they own without the need to re-upload the videos again. The major benefit of this is that you can see consolidated insights for a video and a breakdown of metrics across the multiple posts created from the video. Please see the is_crossposting_eligible and crossposted_video_id field in the Video node and the videos_you_can_use field on the Page node for more information. The videos_you_can_use field tells you if a Page owner has granted permission for you to cross-post it
  • Video Tags - The Video node has a new content_tags field that allows you to add tags to a video. Please see the content_tags field in the Video node for more details.
  • Video Insights - The Video node has a new video_insights edge that contains aggregated video insights from all crossposts across Pages. See the video_insights edge for more information. We have also added Daily Video Metrics, Minutes Watched and 10s metrics to insights edge on the Post Node.

Messenger APIs

  • Webhooks - Added new Page Subscription Fields for Webhooks - (messages, message_deliveries, messaging_optins, messaging_postbacks). These deliver events for the Messenger Platform to receive inbound messages, receive authentication events, delivery confirmations, and postback from buttons on Structured Messages. Please see our implementation guide for more information.

  • Send to Messenger Plugin - We've added a new web plugin to authenticate people into the Messenger Platform so that people can interact with your business over Messenger. Please see our implementation guide for more information.

  • Message Us Plugin - We've added a new web plugin to enable people to start a chat directly with a Page. Please see our implementation guide for more information.

  • Send/Receive API - The Send/Receive API is part of the Messenger Platform. It can be used to send and receive messages between people and Pages. Please see our implementation guide.

Sharing for Devices

  • Sharing for Devices - We're launching a new Sharing for Devices API that lets you share easily from a device to Facebook. Please see our documentation on Sharing for Devices for more information.

Reactions API

  • Reactions API - We've added a new reactions edge for objects that were previously likable. As an example, please see the Post edge for reactions.

Changes from v2.5 to v2.6

Pages

  • The likes field on the Page node has been renamed to fan_count

Marketing API

  • Ads Management
  • Deprecated the connectionobjects API which retrieved all object types and replace it with other APIs that return specific object types. This greatly improves the performance and maintainability. More details here. The new API is at these endpoints:
  • Pages: user_id/accounts
  • Events: user_id/promotable_events
  • Apps: adaccount_id/advertisable_applications
  • Domains: user_id/promotable_domains
  • Sharing a Custom Audience (CA) to Ad Accounts can be done through <CUSTOM_AUDIENCE_ID>/adaccounts API. When a custom audience is shared to a AdAccount, there is a permission setting for sharing it with targeting only or with targeting_and_insights option. Targeting means a recipient ad account can target ads to the audience, insights means the recipient ad account can also use insights tool to view the audience demographics. The default has changed from targeting only to targeting_and_insights in 2.6.
  • Targeting
  • The user_device field is changing to a new format. The old format contains underscores combining brand and marketing name, like ['samsung_galaxy_s6']. The new format contains the device marketing name only, like ['galaxy s6']. Valid values can be retrieved from /search?type=adTargetingCategory&class=user_device. All read requests will be automatically transformed to new format. All writes require the new format.
  • Note that because the values for user_device are different, /reachestimate calls must be made to an object's corresponding version. For example, if an ad set was created in version v2.5 while targeting user_device using the old format, the /reachestimate call for that ad set will return inaccurate values unless it's also made under v2.5.
  • Insights
  • Changed the default for date_preset value from lifetime to last_30_days and fields value from all fields to impressions,spend. Both of these defaults apply to /insights for all object levels.

  • The fields parameter no longer accepts breakdowns such as age or gender. Now you should specified this in breakdowns parameter in query. This includes: age, country, gender, frequency_value, hourly_stats_aggregated_by_advertiser_time_zone, hourly_stats_aggregated_by_audience_time_zone, impression_device, place_page_id, placement, product_id, and region. This applies to /insights for all object levels.

  • Ads Insights API will throw error if since specified in time_range is in the future. Also replace until by today if until is in the future.

  • Dynamic Ads
  • Changed Product Catalog Sales Objective ad set's default optimization_goal to OFFSITE_CONVERSIONS.

  • Default to carousel format. In order to opt-out of carousel format, specify force_single_link=true in object_story_spec.

  • Return an error if no username/password provided for (S)FTP urls when scheduling the product feed. Empty username/password is allowed. e.g. username:"".

  • Lead Ads
  • When querying to retrieve qualifier information for a Lead Ads form, the label and question values of the qualifier are interchanged for Custom Questions. We are fixing this so that moving forward content under label and question will be returned correctly.

90-day changes

  • All Callback Subscriptions Must Use HTTPS - When we launched Graph API v2.5 last October we began requiring new Webhooks (formerly known as Real Time Updates) subscriptions to be configured for HTTPS. With v2.6, this is now required for all new Dynamic Pricing and Deauthorization endpoints as well. Beginning 90 days from today, we will require all callback subscriptions to be configured for HTTPS. At that point, we will stop sending updates to non-HTTPS endpoints, regardless of when they were created. This applies to Webhooks, Webhooks for Payments, Dynamic Pricing, and Deauthorization. You can update your subscriptions on your app dashboard.
  • Rate Limits Changes for Page-related Requests - If you make a request with a Page Access Token, the limits will scale with the number of people engaging with the page. This change will take effect July 11th.

Deprecations in v2.6

Pages Insights

The following Pages Insights have been deprecated. However, each of these has been replaced by another way to query a similar set of insights. Please see our documentation on Page Views for more information. The new insights start with the page_views prefix.

  • page_visits_by_age_gender_logged_in_unique - Total logged-in views count per Page by age and gender (Unique Users)
  • page_visits_by_internal_referer_logged_in_unique - Total logged-in views count per Page by internal referer (Unique Users)
  • page_visits_by_profile_tab_logged_in_unique - Total logged-in views count per Page by profile tab (Unique Users)
  • page_visits_by_profile_tab_total - Total views count per Page by profile tab
  • page_visits_by_site_logged_in_unique - Total logged-in views count per Page by site (Unique Users)
  • page_visits_logged_in_total Total logged-in views count per Page
  • page_visits_logged_in_unique Total logged-in views count per Page (Unique Users)
  • page_visits_total Total views count per Page

Deprecating oauth/device

  • The oauth/device endpoint is deprecated. This affects devices that use this endpoint to generate access tokens. Please use the device/login and device/login_status endpoints instead. See our documentation on logging in with devices for more information.

Marketing API

  • Dynamic Ads
  • Deprecated product_ad_behavior field at the Ad Set level, which is used by Dynamic Ads. Instead we now default all new Ad Sets to FALL_BACK_TO_FB_RECOMMENDATIONS. That means Facebook will automatically choose the highest-performing products from the creative's Product Set to show people who have browsed products that are not in the Product Set.

  • Deprecated <PAGE_ID>/rtb_dynamic_posts for DPA. Use <OBJECT_STORY_ID>/dynamic_posts instead.

  • Deprecated max_product_count since Facebook now automatically optimizes the number of products to show for Dynamic Product ads. In order to opt-out of carousel format, specify force_single_link=true in object_story_spec.

  • Deprecated row_number and column_number fields on product feed upload error /<UPLOAD_ID>/errors, they are available on error samples now.

Other Changes

  • App Role Visibility - Starting with the release of v2.6, an application can no longer see all of the roles that a developer has on other apps. This change also applies to previous versions.

6 Month Deprecations

  • Game Groups Beta - The Game Groups Beta feature, also known as App Groups, is deprecated as a 6 month deprecation. Effective May 1, no new apps may use the Game Groups API. The 6 month deprecation window follows, with final deprecation effective on October 18th.

  • Feed Dialog - Applications using the Feed Dialog will be required to have the publish_actions permission to have access to the returned post_id. The post_id will only be returned if the share generates a story on a person's timeline or in a group. This will take effect on October 11th.

October 7th, 2015 - API version 2.5

New Features

Pages API

  • pages_show_list Permission - GET {user_id}/accounts now require either manage_pages or pages_show_list; the latter is a new permission in v2.5.

  • Managing Call-to-Actions - Pages API can now manage call to actions on a Page:

  • GET page/call_to_actions or GET {call-to-action-id} to read a call to action.
  • POST page/call_to_actions to add a call to action to a page,
  • POST {call-to-action-id} to update.
  • You can now use DELETE {call-to-action-id} to delete a Page's call to action.
  • pages_manage_cta Permissions - POST {page_id}/call_to_actions and POST/DELETE {call-to-action-id} require the new permission pages_manage_cta that we introduce in v2.5.

  • overall_rating Field - A new field overall_rating is added to the Place node. This provides the average rating based on public reviews of a place.

Videos API

Video Upload:

  • Generate Image Slideshows - A new parameter SLIDESHOW_SPEC is added. API users will be able to generate slide show videos by uploading images.

  • Hidden Videos for Page Users - A new parameter SECRET is added for page users only. With this parameter, the published video will not appear on Facebook Newsfeed, Timeline or Page video tabs and is not searchable. A video can be viewed and shared using permalink only.

  • Control Social Actions - A new parameter SOCIAL_ACTIONS is added for page users only. You can use this to enable or prohibit the use of Facebook social actions such as likes, comments, and sharing on an hidden video.

Video Editing:

  • Limit Video Publication - We have a new parameter PUBLISH_TO_VIDEOS_TAB, which will be used to distribute video item publicly to the Page's Videos tab, but not News Feed or Timeline

  • Expand Publication Channels - We added a new parameter PUBLISH_TO_NEWS_FEED, which you can use to distribute video item publicly to News Feed, Page Timeline, and a Page's Videos tab.

Marketing API

  • Lead Ads - Advertisers will now be able to collect contact information and other qualifiers from potential customers via a Facebook ad.

  • Insights - Added inline_link_clicks, cost_per_inline_link_click, inline_post_engagement, cost_per_inline_post_engagement metrics.

  • Ad, Ad set, and Campaign object read path:

    • Add effective_status to reflect the real Ad delivery status. For example for an active adset in a paused campaign, the effective_status of this adset is CAMPAIGN_PAUSED.
    • Add configured_status to reflect the status specified by user.

Changes from v2.4 to v2.5

Pages API

  • Tagged Posts Endpoint - GET {page-id}/feed and GET {page-id}/tagged will include all public posts in which this page is tagged in. You need a page access token with manage_pages permission to get those posts.

Posts

  • story_tags - As of 2.5 this now returns an array, not an object.

Users

  • The address field on the User node will now return an error. The address field, which was available in previous versions and returned an empty value, will return an error as of v2.5.

Real Time Updates API

  • Updating Existing Subscriptions - Existing RTU subscriptions may be modified via the /subscriptions API. POST/subscriptions will amend the subscription for the given topic without overwriting existing fields. You can delete specific fields from your subscription by including a fields param when calling DELETE /subscriptions.

  • Automatically Disable Subscriptions - We now automatically disable RTU subscriptions if the callback URL fails for 7 days straight. You can reenable it with a POST request to /subscriptions. This change does not apply to payments subscriptions.

Marketing API

See table above for future deprecation dates of Marketing API.

  • Consistent naming for three-level campaign structure between API and UI. This changes naming at endpoint, params, fields, and enum level. For the full list of changes, refer here.
  • Change /adcampaign_groups to /campaigns
  • Change /adcampaigns to /adsets
  • Change /adgroups to /ads
  • In the write path, change campaign_group_status, campaign_status, adgroup_status to status
  • Ad Account
  • Default the name of the first visible admin to current user if not specified.
  • Campaign
  • Change naming of objectives
  • WEBSITE_CLICKS to LINK_CLICKS
  • WEBSITE_CONVERSIONS to CONVERSIONS
  • Targeting
  • Response for call to /search?type=adgeolocation will contain only the 'City' instead of 'City, State'
  • Change {cpc, cpm, cpa}_{min, max, median}, such as cpc_min fields in /reachestimate to bid_amount_min, bid_amount_median, bid_amount_max. Change bid_for to optimize_for
  • DPA
  • Enforce Terms of Service for all Product Catalogues and Dynamic Product Ads users. Advertisers implicitly accept by creating their first catalog through Business Manager. For API developers, Terms of Service need to be accepted through BM when the product catalog is first created.
  • Local Awareness Ads
  • Require page_id in promoted_object at the /adset level for Local Awareness Ads
  • No longer require custom_locations for location targeting, and also allow sub-national, single country targeting. Now all location types (except for country) must be within the same country.

Deprecations in this version

90-day deprecations

  • New Real Time Updates via HTTPS Only - New subscriptions cannot be created with a non-HTTPS callback URL. This affects User, Page, App, and Payment updates.

  • Page Tab Apps URI Format - Page Tab Apps URI format https://www.facebook.com/{vanity}?v={app_id} will no longer work 90 days after this release. Please use https://www.facebook.com/{vanity}?sk={app_id} or https://www.facebook.com/{vanity}/{app_id}.

Marketing API

See table above for future deprecation dates of Marketing API

  • The last day to book a PSS (or homepage) campaign will be November 15th
  • The last day PSS (or homepage) campaigns can run will be December 31st 2015.
  • Account
  • Remove friendly_name
  • Campaign
  • Remove ability to create campaign with Objective='NONE'. 'NONE' is still a valid read-only objective. You can continue to edit existing campaigns.
  • Remove REACHBLOCK, DEPRECATED_REACH_BLOCK from campaign buying_type. For older campaigns using these two buying_type, the API will return RESERVED for REACHBLOCK and FIXED_PRICE for DEPRECATED_REACH_BLOCK. FIXED_CPM is replaced with FIXED_PRICE.
  • Adset
  • Remove USE_NEW_APP_CLICK
  • Remove buying_type
  • Targeting
  • Remove want_localized_name param for /search?type=adgeolocation.
  • Remove /search?type=adcity and adregion, use /search?type=adgeolocation instead.
  • Remove engagement_specs and excluded_engagement_specs from targeting spec. The similar video remarketing functionality is supported through /customaudiences endpoint.

Deprecate or make private certain targeting options:

  • Instead of being returned in /search, private categories will now be returned in /act_{AD_ACCOUNT_ID}/broadtargetingcategories or /act_{AD_ACCOUNT_ID}/partnercategories.
  • Deprecated categories will no longer be returned.
  • Updates to ad set targeting using private or deprecated categories will error. It's recommended to query the validation endpoint before updating the ad set targeting to identify which targeting options to remove.
  • Insights
  • Remove filter on adgroup_id, campaign_id, or campaign_group_id. Instead use ad.id, adset.id and campaign.id
  • Note Prior to 2.6 We decided to extend the timeline to deprecate Clicks(All) and CPC metrics until the deprecation of API v2.6. In 2.5, removed cpc and clicks fields in Insights API. Newly added related metrics include inline_link_clicks, cost_per_inline_link_click, inline_post_engagement, cost_per_inline_post_engagement. Please note clicks(all) historically counted any engagement taken within the ad unit as a click. Thus, clicks(all) won't be a simple addition of link_clicks and post_engagement. The newly added fields are available in v2.4 and v2.5.
  • Reach Estimate - Require optimize_for at the /reachestimate endpoint.

The next version of the Graph API will be released in April 2016. We'll announce a specific date in the near future.

July 8th, 2015 - API version 2.4

New Features

Page Video Insights

In v2.4 we expose a set of new Page Video metrics, such as page_video_views_paid, page_video_views_autoplayed, and page_video_views_organic available from the Graph API via GET /v2.4/{page_id}/insights/?metric={metric}. These metrics require the read_insights permission.

New Video Features

The Video node now contains the following fields in GET|POST operations to /v2.4/{video_id}:

  • content_category which supports categorizing a video during video upload, and can be used for suggested videos. Content categories include: Business, Comedy, Lifestyle, etc and a full list of categories can be viewed on the Video node docs page.
  • unpublished_content_type will expose 3 new types (Scheduled, Draft, and Ads_Post) which will help coordinate how the video is posted.
  • expiration and expiration_type allows the video expiration time to be set, along with the type (hide, delete).
  • embeddable boolean flag is now available to control if 3rd party websites can embed your video.

Accessing Timeline Posts

We've simplified how you access content on a person's Timeline. Instead of handling different object types for statues and links, the API now returns a standardized Post node with attachments which represent the type of content that was shared. For more details view the User reference docs.

For Marketing API

For Marketing API (formerly known as Ads API) v2.4 new features, see Facebook Marketing API Changelog.

Changes from v2.3 to v2.4

Permission related changes

  • Operations that reference the admin_creator object of a Post in now requires a Page access token.
  • POST /v2.4/{page_id}/offers and DELETE /v2.4/{offer_id} now require a Page access token with manage_pages and publish_pages permissions.
  • GET /v2.4/{page_id}/milestones, POST /v2.4/{milestone_id}, and DELETE /v2.4/{milestone_id} now require a Page access token with manage_pages and publish_pages permission.

Changes to Pages APIs

  • Calls made to the Page node GET /v2.4/{page_id}/promotable_posts now require a user access token with ads_management permission or a Page access token.
  • The global_brand_parent_page object has been renamed to global_brand_root_id.
  • GET /v2.4/{global_brand_default_page_id/insights will now return only insights of the default Page insight data, instead of the insights for the Global Brand hierarchy. Use the Root Page ID to retrieve the integrated insights of the whole hierarchy.
  • GET|POST /v2.4/{page_id}/promotable_posts has renamed the field is_inline to include_inline.
  • The maximum limit for Page related objects is now set to limit=100. This will impact GET operations made on the feed, posts, and promotable_posts edges.

Event Ordering

The default pagination ordering of GET {user-id}/events now begins with the newest event first, and is ordered in reverse chronological order.

Improved Filtering

Graph API v2.4 now supports filtering of GET /v2.4/{user_id}/accounts with new boolean fields:

  • is_promotable filter results by ones that can be promoted.
  • is_business filter results associated with a Business Manager.
  • is_place Include Place as results filter.

Declarative Fields

To try to improve performance on mobile networks, Nodes and Edges in v2.4 requires that you explicitly request the field(s) you need for your GET requests. For example, GET /v2.4/me/feed no longer includes likes and comments by default, but GET /v2.4/me/feed?fields=comments,likes will return the data. For more details see the docs on how to request specific fields.

Deprecations in this version

2-year deprecations

  • GET /v2.4/{id}/links and GET /v2.4/{id}/statuses will no longer be available beginning in v2.4. As an alternative, we suggest using GET /v2.4/{id}/feed.
  • GET|POST /v2.4/{page_id}/?fields=global_brand_parent_page is being deprecated in this version and replaced by /v2.4/{page_id}/?fields=global_brand_root_id.
  • GET|POST /v2.4/{page_id}/global_brand_default_page_id/global_brand_children will no longer function in v2.4. As an alternative, please use the root page ID.
  • GET /v2.4/{page_id}/promotable_posts will no longer support the filter and type params in v2.4. For example, a call to GET /v2.4/{page_id}/promotable_posts?type=STATUS will return an empty result set.
  • The Event node no longer supports GET operations on the endpoints /v2.4/{event_id}/invited, /v2.4/{event_id}/likes, or /v2.4/{event_id}/sharedposts.

90-day deprecations (effective Tuesday, October 6, 2015)

  • The GET /v2.4/{user_id}/home, GET /v2.4/{user_id}/inbox, and GET /v2.4/{user_id}/notifications operations as well as read_stream, read_mailbox, and manage_notifications permissions are deprecated in v2.4.
  • the user_groups permission has been deprecated. Developers may continue to use the user_managed_groups permission to access the groups a person is the administrator of. This information is still accessed via the /v2.4/{user_id}/groups edge which is still available in v2.4.
  • GET /v2.4/{event_id}/?fields=privacy is deprecated in v2.4.
  • GET /v2.4/{event_id}/?fields=feed_targeting is deprecated in v2.4.
  • GET /v2.4/{event_id}/?fields=is_date_only is deprecated in v2.4.

From October 6, 2015 onwards, in all previous API versions, these endpoints will return empty arrays, the permissions will be ignored if requested in the Login Dialog, and will not be returned in calls to the /v2.4/me/permissions endpoint.

Next Steps

Read Upgrade Guide (v2.4)

March 25th, 2015 - API version 2.3

New Features

  • user_posts Permission - We have a new permission user_posts that allows an app to access the posts on a person's Timeline. This includes the someone's own posts, posts they are tagged in and posts other people make on their Timeline. Previously, this content was accessible with the read_stream permission. The user_posts permission is automatically granted to anyone who previously had read_stream permission.

  • all_mutual_friends Edge - This Social context edge enables apps to access the full list of mutual friends between two people who use the app. This includes mutual friends who use the app, as well as limited information about those who don't.

Both users for whom you're calling this endpoint must have granted the user_friends permission.

If you calling this endpoint for someone not listed in your app's Roles section you must submit your app for review by Facebook via App Review.

Although this edge is new to Graph API v2.3, to make it easier for you to migrate we also added this edge to v2.0, v2.1, and v2.2.

  • Debug Mode - Provides extra information about an API call in the response. This can help you debug possible problems and is now in Graph API Explorer, as well as the iOS and Android SDKs. For more information see Graph API Debug Mode.

  • New Pages Features

  • Real-time Updates - As of March 25, 2015 We now send content in Page real-time updates (RTUs). Previously, only the object's ID was in the RTU payload. Now we include content in addition to the ID including: statuses, posts, shares, photos, videos, milestones, likes and comments. In order for the app to receive these types of updates, you must have enabled the "Realtime Updates v2.0 Behavior" migration in your app's dashboard.

  • Page Reviews now support real-time updates. Apps can subscribe to the ratings property to receive a ping every time a public review is posted on pages the app is subscribed to. In order for the app to receive this type of update, you must have enabled the "Realtime Updates v2.0 Behavior" migration in your app's dashboard.

  • Page Posts, admin_creator - All Page Posts now include a new admin_creator field that contains the id and name of the Page Admin that created the post. This is visible when you use a Page access token, or the user access token of a person who has a role on the Page.

  • New Page Fields -GET|POST /v2.3/{page-id} now supports fetching and updating these fields: emails, food_styles, public_transit, general_manager, attire, culinary_team, restaurant_services, restaurant_specialties, and start_info.

  • New Page Settings - GET|POST /v2.3/{page-id}/settings now supports four new settings: REVIEW_POSTS_BY_OTHER, COUNTRY_RESTRICTIONS, AGE_RESTRICTIONS, and PROFANITY_FILTER.

  • Larger Videos with Resumable Upload - We now support larger video sizes uploads up to 1.5GB or 45 minutes long with resumable video upload. See Video Upload with Graph API.
  • File URL Parameter - At all /v2.3/{object_id}/videos edges you can create a new Video object from the web by providng the file_url parameter.
  • Resumable, Chunked Upload - All /v2.3/{object_id}/videos edges support resumable, chunked uploads. For more information, see Video Upload with Graph API.
  • Video Playlists - You can now create and manage video playlists for Pages by using GET|POST|DELETE on the /v2.3/{page_id}/videolist edge. you can also add videos to a playlist by POST /v2.3/{videolist_id}/videos and GET the videos of a playlist.

  • Page's Featured Video - You can now set and get the featured_video of a page using GET|POST /v2.3/{page_id}/featured_videos_collection.

  • Publish Fields - All Video nodes objects at /v2.3/{video_id} now return the new fields: published, a boolean which indicates if the video is currently published, and scheduled_publish_time.

  • Custom Thumbnail - You can now upload and manage custom video thumbnails as JPEGs or PNGs with GET|POST /v2.3/{video_id}/thumbnail. See Graph API Reference, Video Thumbnail.

  • Targeting Restrictions - POST /v2.3/{page-id}/videos now supports targeting restrictions by country, locale, age range, gender, zipcode, timezone and excludin locations.

  • Delete - DELETE /v2.3/{video_id} removes videos. This is supported if you have edit permissions on the video object.

  • New Read and Write Fields - The Video node now supports retrieving and modifying additional fields: backdated_time, and backdated_time_granularity.

  • Subtitles, Localized Captions - GET|POST /v2.3/{video-id} now supports supplying and retrieving subtitles and localized captions.

  • Visibility of Video - With POST /v2.3/{page_id}/videos you can control where the video is seen with no_story and backdated_post.hide_from_newsfeed parameters. These parameters target visibility on feeds and page timelines.

Changes from v2.2 to v2.3

  • Page Plugin - Is the new name for Like Box Social Plugin and it has a new design.

  • Comments Plugins Has a new design and it now supports Comment Mirroring (private beta).

  • Requests are now GameRequests - Previously this term and object-type created confusion for non-game app developers, and the intended usage of these objects are to invite others to a game Non-game apps should use App Invites. The /v2.3/{user-id}/apprequests edge is now limited to game apps. See Games, Requests.

  • read_custom_friendlists - Is the new name for read_friendlists Login permission. This is to clarify that the permission grants access to a person's custom friendlists, not the full list of that person's friends.

  • Changes to Page APIs:

  • publish_pages Permission - This new permission is required to publish as a Page. Previously publish_actions was required. People who granted manage_pages and publish_actions before v2.3 have automatically been granted publish_pages. If anyone logs in via v2.3, you'll need to request publish_pages explicitly in addition to manage_pages.

  • Page Publish Operations - now accept the type of access token the requests are made with. This includes publishing posts, likes and comments. When a user access token of a Page admin is in the request such as POST /v2.3/{page-id}/feed, the action occurs with the voice of the user, instead of the Page. To publish as the Page, you must now use the Page access token.

  • Removing Comments on Page posts - As a Page admin with DELETE /v2.3/{comment-id} now requires a Page access token.

  • POST /v2.3/{page-id} - Now requires country as sub-parameter if you update the location field without specifying the city_id sub-parameter. The state sub-parameter is also required if country sub-parameter is 'United States'.

  • Countries - The country subfield of the feed_targeting field on a Page post is renamed countries when you make a POST|GET /v2.3/{page-id}/{post-id}.

  • Page Field Updates - POST /v2.3/{page-id} - Now supports complete field updates for: hours, parking, payment_options.
    Previously, the update behavior on these fields was to replace a specific key/value pair that was specified as part of the POST, leaving all other keys intact, but the new functionality of a POST on one of these fields will replace all key/value pairs with what is posted.

  • Premium Video Metrics - Insights for Page Premium Video Posts are now deprecated.

  • page_consumptions_by_consumption_type insight now returns data for a local page instead of a parent - In earlier versions of the insights API for a Page, asking for this insight would return data for a parent of a local page. In v2.3, we now return the data for only that local page.

  • Picture Error - For the Link, Post, Thread, Comment, Status, and AppRequest nodes, and other nodes which don't have a picture, the /v2.3/{object}/picture edge now returns an error message. Before, the API returned a placeholder image of a 'question mark' for the picture edge requested on these nodes.

  • [Oauth Access Token] Format - The response format of https://www.facebook.com/v2.3/oauth/access_token returned when you exchange a code for an access_token now return valid JSON instead of being URL encoded. The new format of this response is {"access_token": {TOKEN}, "token_type":{TYPE}, "expires_in":{TIME}}. We made this update to be compliant with section 5.1 of RFC 6749.

  • Consistent Place Data - Content objects tagged with a place now share a consistent place data structure which contains the ID, name, and the geolocation of the place. This includes Events, Photos, Videos, Statuses and Albums. As a result, the venue and location fields have been removed from the Event node. Developers should access the place field instead.

In addition, if someone tags a Photo, Video, Status, or Album at an event, that object will contain an event field.

  • Serialized Empty Arrays - All Graph API endpoints now consistently serialize empty arrays as [] and empty objects as {}. Previously, some empty objects were incorrectly serialized as empty arrays.

  • Default Result Limit - All edges will now return 25 results per page by default when the limit param is not specified.

  • Ads API now Marketing API - We recently renamed the Facebook Ads API to the Facebook Marketing API. For details on Marketing API changes see the Marketing API v2.3 Changelog.

90-day deprecations (effective Tuesday, June 23, 2015)

  • Edges and Permissions - /v2.3/{user_id}/interests and /v2.3/{user_id}/activities edges as well as user_interests and user_activities permissions are deprecated in v2.3.

From June 23, 2015 onwards, in all previous API versions, these endpoints will return empty arrays, the permissions will be ignored if requested in the Login Dialog, and will not be returned in calls to the /v2.3/me/permissions endpoint.

  • Page RSS Feed endpoint - at https://www.facebook.com/feeds/page.php is now deprecated and will stop returning data from June 23, 2015. Developers should call the Graph API's /v2.3/{page_id}/feed endpoint instead. This returns JSON rather than RSS/XML.

  • Social Plugins - The following are now deprecated and will no longer render after June 23, 2015:

  • Facepile Plugin
  • Recommendations Feed Plugin
  • Activity Feed Plugin
  • Like Box Social Plugin

October 30th, 2014 - API version 2.2

New Features

  • Developers may now hide and unhide comments on a Page Post via the Graph API: POST /v2.2/{comment_id}?is_hidden=true to hide, POST /v2.2/{comment_id}?is_hidden=false to unhide. You can determine if a comment is hidden, or if you have the ability to hide/unhide the comment by checking the is_hidden or can_hide fields on the comment node.
  • A new token_for_business field makes it easier to identify the same person across multiple apps owned by the same business: In addition to the Business Mapping API, there is now a new token_for_business field on the user object. This emits a token which is stable for the same person across multiple apps owned by the same business. This will only be emitted if the person has logged into the app. For games developers, this property will also be emitted via the signed_request object passed to a canvas page on load. Note that this is not an ID - it cannot be used against the Graph API, but may be stored and used to associate the app-scoped IDs of a person across multiple apps. Also note that if the owning business changes, this token will also change. If you request this field for an app which is not associated with a business, the API call will return an error.
  • The comment node has a new object field which emits the parent object on which the comment was made. To get the ID and owner of the comment's parent object (for example, a Page Post) you might call: /v2.2/{comment_id}?fields=object.fields(id,from)
  • The Page node has a new edge to manage subscriptions for realtime updates.
  • In previous versions, any app which was added as a Page Tab also received realtime updates. From v2.2 onwards there is a dedicated endpoint for managing these subscriptions:
    • GET /v2.2/{page-id}/subscribed_apps returns the apps subscribed to realtime updates of the Page. This must be called with a Page Access Token.
    • POST /v2.2/{page-id}/subscribed_apps subscribes the calling app to receive realtime updates of the Page. This must be called with a Page Access Token and requires the calling person to have at least the Moderator role on the Page.
    • DELETE /v2.2/{page-id}/subscribed_apps stops the calling app from receiving realtime updates of the Page. This may be called with a Page or App Access Token. If called with Page Access Token, it requires the calling person to have at least the Moderator role on the Page.
  • The feed_targeting parameter is now supported when publishing videos to a Page: POST /v2.2/{page_id}/videos?feed_targeting={targeting_params}. This lets you specify a number of parameters (such as age, location or gender) to help target who sees your content in News Feed. This functionality is already supported on POST /{page_id}/feed so we're extending this to videos too.
  • The Page node has a number of new writeable fields to let apps update a Page's information: The following fields are now supported with POSTing to /v2.2/{page_id}:
  • payment_options takes an object which lets you specify the payment options accepted at the place.
  • price_range accepts an enum of strings which represent the self reported price range of the Page's business.
  • latitude and longitude can now be specified as properties of the location field in order to let apps programmatically update Page's physical location. Both are floats.
  • ignore_coordinate_warnings (boolean) determines if the API should throw an error when latitude and longitude are specified in location field for updating the Page's location. If set to false, an error will be thrown if the specified coordinates don't match with the Page's address.
  • is_always_open lets apps set the status of the place to “Always Open”. This can only be set to true, and will clear previously specified hours in hours field. To set specific hours, use hours field.
  • is_published takes a boolean which lets you publish or unpublish the Page. Unpublished pages are only visible to people listed with a role on the Page.
    • The Page node has a new readable field to let apps read a Page's information: The following field are now supported with a GET to /v2.2/{page_id}:
  • name_with_location_descriptor returns a string which provides additional information about the Page's location besides its name.
    • There's a new APPEARS_IN_RELATED_PAGES setting on /v2.2/{page_id}/settings. This boolean determines if your page can be included in the list of suggested pages which are presented when they like a page similar to yours. You may set or read this value.
    • You can now read the permissions your app has been approved for via an API. A new edge on your App object, called /{app-id}/permissions, allows you to view the permissions that your app has been approved for via Login Review.

Changes

  • There's now a limit of 50 IDs which can specified in a single request using the syntax ?ids=ID1,ID2. This reduces the likelihood of timeouts when requesting data about a large number of IDs in a single request.
  • The blocked edge on the Page node now requires a Page Access Token - this endpoint can no longer be called with an App or User token. That endpoint is available at: GET|POST|DELETE /v2.2/{page_id}/blocked?access_token={page_access_token}.
  • The tabs edge on the Page node now requires a Page token for GETs. POSTs and DELETEs on this endpoint already require page tokens. That endpoint is available at: GET|POST|DELETE /v2.2/{page_id}/tabs?access_token={page_access_token} Calling GET on this edge now works for people in the 'Analyst' role. It previously required the 'Editor' role.
  • The tabs edge on the Page node will now throw an error if the caller does not have permission. Previously it would only return an empty string.
  • The /{page_id}/admins edge on the Page node has been renamed to /v2.2/{page_id}/roles. In addition, in the response, the values returned in the role field have been changed:
  • MANAGER has been renamed to Admin.
  • CONTENT_CREATOR has been renamed to Editor.
  • MODERATOR has been renamed to Moderator.
  • ADVERTISER has been renamed to Advertiser.
  • INSIGHTS_ANALYST has been renamed to Analyst.
  • The settings edge on the Page node will no longer include entries for settings where the value field would be null.
  • POST /{page_id}/settings will no longer support the setting and value params. Instead, you should specify the option param which should be an object containing a single key/value pair with the setting enum as the key.
  • From v2.2 onwards, apps calling GET /v2.2/{page_id}/notifications must use a Page Access Token. Previously this required the manage_notifications permission. User Access Tokens will no longer work for this endpoint.
  • The structure of the /v2.2/{group_id}/albums endpoint has changed to match the response of /{user_id}/albums.
  • The number of results returned from the /v2.2/me/friends endpoint now defaults to 25.

90-day deprecations (effective Wednesday, January 28, 2015)

  • The fb:name social plugin has been deprecated and will stop working on Jan 28, 2015. Developers should instead use the FB.api() method of the Javascript SDK to retrieve the names of users.
  • In versions previous to v2.2, it was possible for an app to see if a person like the app's page by checking the page_fan FQL table or the /{user_id}/likes/{app_page_id} Graph API endpoint without needing the user_likes permission. Starting in v2.2, the user_likes permission will be required to query these endpoints. Also, we will require the user_likes permission on versions older than v2.2 starting 90 days from today, on Jan 28, 2015. Facebook will not grant the user_likes permission solely for the purpose of checking if a person has liked an app's page. This change was announced on August 7, 2014 and will come into effect on November 5, 2014.
  • The Pages JSON feed (e.g. https://www.facebook.com/feeds/page.php?id=%2019292868552&format=json) is now deprecated and will stop returning data from Jan 28, 2015 onwards. Developers should instead call the feed edge on the Graph API's Page object: /v2.2/{page_id}/feed.
  • POST /{page-id}/tabs and DELETE /{page-id}/tabs will no longer support subscribing or unsubscribing an app for realtime updates. This will take effect in all previous API versions on January 28, 2015. To subscribe an app to realtime updates for a page, use the new /v2.2/{page_id}/subscribed_apps endpoint.
  • The Comments Plugin will no longer support commenting via third-party identifiers after January 28, 2015. This facility was rarely used and the majority of comments posted by these accounts were of low quality. People may still comment using their Facebook account, or may also comments as a Facebook Page.

October 14th, 2014 - Disabled SSL 3.0 Support

On October 14, 2014, we dropped support for SSL 3.0 across Facebook properties, including the Facebook Platform API and the Real-Time Updates API, after a vulnerability in the protocol was revealed on October 14, 2014. This change helps protect people’s information.

If your HTTP library forces the use of SSL 3.0 rather than TLS, you will no longer be able to connect to Facebook. Please update your libraries and/or configuration so that TLS is available.

August 7, 2014 - API version 2.1

This is Facebook's first new API update after version 2.0 was launched at the 2014 f8 conference. API versions are supported for two years after the next version is released. This means that:

  • Version 2.1 will be available starting today until two years after the release of a post-v2.1 version.
  • Version 2.0 will expire on August 7, 2016, two years after the release of v2.1. (Version 2.0 was introduced on April 30, 2014.)
  • Version 1.0 will expire as scheduled on April 30, 2015.

New Features

  • Pages can mention other Pages when publishing via API: When making calls to several Page publishing edges such as /feed or /photos you can now mention other Pages in a message field. This extends our current availability of mentions in Open Graph. This API requires review by Facebook before it can be used by people other than the app’s developers. Learn more about the Page Mentions review process in our documentation.
  • New total friend count on the friends connection: /v2.1/me/friends (and /v2.0/me/friends) now provides access to total friend count - this count includes friends who use the app as well as those who don't.
  • New 'facebook-api-version' HTTP header: In all API versions, we now return an HTTP response header called 'facebook-api-version' which indicates which API version your app is actually experiencing - this may be different to the API version you specify in your request due to upgrades.
  • New App Insights API: v2.1 includes access to the new App Insights data via an API. This is available by calling /v2.1/{app_id}/app_insights
  • A new format for Graph API Field Expansion: v2.1 introduces more concise syntax for Field Expansion. (The new syntax is also been added to v2.0 and earlier). See our documentation on field expansion for examples. The older format for field expansion is still available, but the new format is preferred.
  • User-facing error messages: In some cases (such as access token invalidation or expiry) the API now returns user-displayable error messages which describe the error and what the person may need to do to resolve it. These error messages will be returned in US English by default, but if you query the Graph API specifying the locale parameter (e.g. ?locale=es_ES) the string may be returned in the specified language.
  • The Event object now has five new integer fields: attending_count, declined_count, maybe_count, noreply_count and invited_count: Each of these returns an integer which represents the number of people who have been invited, not replied, are attending, are not attending or whom may attend.
  • GET /v2.1/?id={url} returns a new URL node: In v2.1, when you query the Graph API with a URL as the ID, we'll return a URL object which enumerates any share info available for that URL, any Open Graph object associated with that URL, or any AppLinks that use the URL.
  • The Page object now has a new screennames edge: this returns a list of the other, non-Facebook accounts associated with the brand or entity represented by a Facebook Page.

Deprecations in this version

  • The FQL and REST APIs are no longer available in v2.1: Previously announced with v2.0, apps must migrate to versioned Graph API calls starting with v2.1.
  • The '/insights' edge on the Application object is no longer available in this version: This has been replaced by the new '/app_insights' edge.

90-Day Deprecations

The following deprecations will take place on November 5, 2014 - 90 days after the launch of v2.1.

  • The Recommendations Bar social plugin has been deprecated: On Wednesday November 5th 2014, the Recommendations Bar will no longer render on any website. If you're using this plugin, we recommend you remove it from your site before this date.
  • The /insights edge on the Application object will be removed in both v1.0 and v2.0: The insights API is classified as an Extended API and is subject to change within the life of a version. Developers should instead move to call /v2.1/{app_id}/app_insights before this deprecation takes effect.
  • The 'liked' property will no longer be returned in the 'signed_request' object for Page Tab apps created after today. From November 5, 2014 onwards, the 'liked' property will always return 'true' regardless of whether or not the person has liked the page.

Changes

  1. API responses are now always JSON objects, rather than booleans, integers or strings: Many API calls before v2.1 returned plain text 'true' or a raw number like '378293782' as the response. With v2.1, those calls will now return valid JSON, such as: { “success”: true }
  2. The dialogs/oauth endpoint no longer support the 'return_session' and 'session_version' parameters for legacy authentication methods.
  3. /v2.1/me/permissions no longer contains the 'installed' permission: 'installed' was a pseudo-permission that was used to check if someone had your app installed. Instead of looking for 'installed' in the response, you should call the endpoint and, if it returns data, consider this indication that the user has installed the app.
  4. GET /?id={your_url} for Open Graph object and Shares has been replaced by new URL node: Previously, when you queried the Graph API with a URL as the ID, we returned information related to shares of that URL. If the URL was also an Open Graph object, you would have to specify 'type=og' in your request. Version 2.1 introduces a new URL node which combines and replaces this functionality.
  5. /v2.1/{post-id} will now return all photos attached to the post: In previous versions of the API only the first photo was returned with a post. This removes the need to use FQL to get all a post's photos.
  6. 'uri' can no longer be requested from picture fields: Apps previously requesting uri should instead use url.

Changes to Platform Policies

  • Games which include mandatory or optional in-app charges must now disclose this in their app's description, either on Facebook or other platforms it supports. This is to give people a clear indication that your game may charge people during gameplay.
  • You must not incentivize people to use social plugins or to like a Page. This includes offering rewards, or gating apps or app content based on whether or not a person has liked a Page. It remains acceptable to incentivize people to login to your app, checkin at a place or enter a promotion on your app's Page. To ensure quality connections and help businesses reach the people who matter to them, we want people to like Pages because they want to connect and hear from the business, not because of artificial incentives. We believe this update will benefit people and advertisers alike.

These policy changes will come into effect on November 5, 2014 - 90 days after the launch of v2.1. They apply to all apps across all API versions.