Facebook Platform Changelog

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 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.

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_amout_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, and all locations 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

• Premium Self Serve

  • 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 reach_block, deprecated_reach_block and FIXED_CPM from campaign buying_type.

• 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
  • Remove cpc and clicks fields in Insights API. Use newly added inline_link_clicks, cost_per_inline_link_click, inline_post_engagement, cost_per_inline_post_engagement as alternatives. The newly added fields are available in v2.4 and v2.5

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

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.

• Videos New Features

  • 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 suppogrts 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.

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

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.

• 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 the location 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.

April 30th, 2014 - API Version v2.0

Graph API v2.0 was introduced at the 2014 Facebook Developer Conference (f8). This changelog entry covers a large number of products and services, broken out by topic. This is the first release of Facebook's API that is versioned.

As the oldest active version of the API, unversioned calls to the Graph API will be made against this version.

Facebook Login

Version 2.0 includes a new version of Facebook Login. It has a new design that gives people more control about the info they share with your app:

• Permissions are now optional to people using your app: People using your app can now choose whether or not to give you the info that you request. The login dialog offers the ability to decline any of the permissions your app requests.
• Friend list is no longer part of the default permission set and has its own permission: Asking for access to a person's friend list is now a separate permission that your app must request. The new permission is called user_friends.
• Friend list now only returns friends who also use your app: The list of friends returned via the /me/friends endpoint is now limited to the list of friends that have authorized your app.
• The default permission set called "basic info" has been removed, and replaced by "public profile": The old default permission, called basic_info has been replaced by public_profile. public_profile does not include a person's friends. Specifying it as part of the initial login request is still required on iOS and Android.
• We will review how apps use Facebook Login: Apps requesting more than public_profile, email and the user_friends permission must be reviewed by Facebook before those permissions can be requested from people. Active apps created before April 30th, 2014 have one year before they are required to go through login review, including updates to existing apps. Facebook apps created after April 30th, 2014 must go through review.

Anonymous Login (Beta)

Anonymous Login is a new product from Facebook that lets people log into your app without sharing any personal information. To learn more and apply for early access, please see our [Anonymous Login product page].

Audience Network

We now provide a widget for iOS and Android that you can use to deliver high-quality, relevant ads to people using your app.

Message Dialog

Let the people using your app easily share things with their friends via private messages in Facebook Messenger, without requiring Facebook Login. The message dialog is available on iOS and Android.

App Links

App Links is an open, cross platform solution for app to app linking. App Links provides all the tools you need to expose deep links in your app or to have your app link out to others in the ecosystem.

Learn more about app links at applinks.org and how to integrate them into your app with our iOS and Android documentation.

Like Button for Mobile

We're introducing a new Like button for mobile apps, available in beta on iOS. The Like Button is the fastest way to share stories with your friends.

New PHP SDK for Facebook

We've created an all-new version of our PHP SDK that's been completely rebuilt and takes advantage of the language features of PHP 5.4 and above.

API Versions

The Graph API now supports versioning. APIs defined as Core will be supported for at least two years. Core APIs include features such as Facebook Login, the Like button, many endpoints on the Graph API, and our iOS and Android SDKs.

Parts of the API that aren't marked as Core APIs may may still use migrations to modify their behaviour within a give API version. Please see our document on versions and our upgrade guide for more information.

JavaScript SDK

• New path: In order to support Graph API versioning and the new Facebook Login, the JS SDK must be loaded from a new path. The old location was https://connect.facebook.net/en_US/all.js and the new location is https://connect.facebook.net/en_US/sdk.js.
• FB.init() now supports versions: FB.init() takes a new parameter: version that indicates what version of the API you would like to use (such as "v2.0").
• Many parameters to FB.init() now default to false. In particular, the status flag.

Graph API

Changes from v1.0 to v2.0

• App-scoped User IDs: To better protect people's information, when people log into your app, Facebook will now issue an app-scoped ID rather than that person's orginal ID. However, for users that have previously logged into your app, the user ID will not change.
• App Friends: The /me/friends endpoint no longer includes the full list of a person's friends. Instead, it now returns the list of that person's friends who are also using your app.
• All requests to Graph API v2.0 require an access token, except for /{id}/picture.
• The format of the /me/permissions endpoint has changed. It now includes a list of permissions and a status field denoting if they were granted or declined.

New features available in v2.0

• Taggable Friends API: We've added a new endpoint called /me/taggable_friends that you can use in order to generate stories that have friends tagged in them, even those friends don't use your app. If you want to use the taggable friends API, your app will require review.
• Invitable Friends API: We've added a new endpoint called /me/invitable_friends that you can use to generate a list of friends for someone to invite to your game through a custom interface. This API is only available to apps that are games on Facebook Canvas.
• Social Context API: We've added a new endpoint to objects and apps that allow you to display a person's friend's actions on an object. For example, you might be able to answer the question "Which of my friends have watched this movie?" by looking at the /{movie-id}?fields=context endpoint. Or you could answer the question "Which of my friends play this game?" by looking at the /{game-app-id}?fields=context endpoint. The game app example is particularly useful for games that want to do cross-game promotions.
• Business Mapping API: With this release, a number of apps can be owned by a single businesses. Along with the move to emit app-scoped user IDs, we're introducing a new endpoint called /me/ids_for_business that allows you to correlate a user's IDs across multiple apps associated with the same Business as defined within Business Manager.
• Tagged Places API: We're adding a new endpoint called /me/tagged_places that lets you access all the Places a person has been tagged at in photos, videos, statuses and links. There is a new permission associated with this endpoint: user_tagged_places.

Endpoints no longer available in v2.0

• /me/locations has been removed. Please use /me/tagged_places instead.
• /me/checkins has been removed, along with the user_checkins permission.
• /me/questions has been removed, along with the user_questions permission. This also includes /{page-id}/questions, /{group-id}/questions, /{question-id} and /{question-option-id}.
• /me/subscribers and /me/subscribedto have been removed.
• /me/username is no longer available.
• /me/notes is no longer available, along with the user_notes permission.
• /{page-id}/notes is no longer available.
• /{page-id}/questions is no longer available.
• Public Post search is no longer available. (/search?type=post&q=foobar)
• News Feed search is no longer available (/me/home?q=foobar)
• Start Now is no longer available in v2.0.

Permissions

Changes from v1.0 to v2.0

• In Graph API v2.0, access to /me/friends is no longer part of the default (public_profile) permissions. We now require you to ask for the new permission user_friends. With this permission, /me/friends now returns the person's friends who are also using the app.
• Apps using Facebook Login that require more than public_profile (default), email and user_friends will require review by Facebook in order to request these permissions from people.
• The permission read_friendlists no longer allows you to read the list of friends in a friendlist, but only lets you access the name of the list. This is useful for people building custom audience selectors when posting stories.
• The permissions at the /me/permissions endpoint now indicate if the permissions were granted or declined in the Facebook Login dialog.

New permissions in v2.0

• We've added the new public_profile permission to replace basic_info as the default. public_profile contains much of the same information as basic_info did, but without the person's friends listed.
• As mentioned above, the user_friends permission is new in v2.0. It gives you access to the /me/friends endpoint, which lists the person's friends who also use your app.
• We've added a new permission called user_tagged_places. This gives you access to a new endpoint, /me/tagged_places, which replaces the deprecated user_location permission.

Permissions no longer available in v2.0

• basic_info is no longer available.
• create_event is no longer available.
• manage_friendlists is no longer available.
• read_requests is no longer available.
• user_checkins is no longer available
• user_notes is no longer available.
• user_online_presence is no longer available.
• user_questions is no longer available.
• user_subscriptions is no longer available.
• xmpp_login is no longer available.

All friends_* permissions have been removed. They include:

• friends_about_me
• friends_actions.books
• friends_actions.fitness
• friends_actions.music
• friends_actions.news
• friends_actions.video
• friends_actions:APP_NAMESPACE
• friends_activities
• friends_birthday
• friends_checkins
• friends_education_history
• friends_events
• friends_games_activity
• friends_groups
• friends_hometown
• friends_interests
• friends_likes
• friends_location
• friends_notes
• friends_online_presence
• friends_photos
• friends_questions
• friends_relationships
• friends_relationship_details
• friends_religion_politics
• friends_status
• friends_subscriptions
• friends_videos
• friends_website
• friends_work_history

Dialogs

• The friends dialog is no longer available.
• The registration plugin is no longer available.
• The feed and legacy share dialogs are now deprecated. They will continue to work, but we strongly recommend upgrading to the newer, modern Share dialog which additionally allows Open Graph stories to be published.
• In the feed dialog, the to: parameter will no longer accept arbitrary user IDs. You may only pass in the IDs of people who also use your app.

FQL

FQL is still available in version 2.0, but will not be available in the next version of the API. This early warning is given so that developers can start migrating off FQL to the Graph API as soon as possible. We strongly recommend that developers build no new experiences based on FQL. The vast majority of use cases can be achieved using the Graph API including field expansion and batched requests.

Test Apps

You can now create test versions of your production apps for use in development, testing, staging and QA. Test Apps are linked with your production app, but have their own app ID and settings. Test Apps are always in development mode. They share the same app-scoped user IDs as their production app. Admins of the production app have one place to manage all of the people who have access to the production and test apps.

Learn more in our documentation for test apps.

Business Mapping API

For businesses that operate multiple user-facing apps (for example, game developers), the Business Mapping API allows them to correlate a given user's IDs across the multiple apps operated by that business. To enable this API, developers must associate their apps with a parent business using a new tool called Business Manager. Learn about how to use the Business Mapping API and Business Manager.

Games

The following changes have been made to the app and games group API:

• Apps Can Post as Apps - Apps can now post to groups as apps in addition to posting on behalf of the user.
• Create Group Dialog - Apps can now show a client-side dialog as an alternative to creating groups server-side.
• Join Group Dialog - Apps can now show a client-side dialog as an alternative to adding users to a group on the server-side.
• Add user to group by API removed - Apps can no longer add any user to a group via API. They can only add users that have a role on the app(admins, developers, testers, test users).
• Read Feed Removed - Apps can no longer read a group feed. However, apps can view the posts they make via the Graph API. Apps can also comment on their posts using this same API.
• Create event Removed - Apps can no longer create events with the API.
• Delete a group has changed - Apps can only delete groups that have no members in them. If the app wants to delete a group, they must remove all members first. Deleting a group will make it non-existent.
• Removed requirement for user_groups permission - Apps should not ask for the user_groups permission to get a list of user's groups. Apps can now get a user's game groups that belong to an app (and that app only) without the permission.
• Removed App Center requirement - We removed the requirement for an app to be in App Center in order to use Game Groups.

Chat

The Chat/XMPP service and API was deprecated along with Graph API v1.0 on April 30, 2015.