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.4, which was introduced on July 8, 2015.
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.
Versions:
Version | Path | Date Introduced | Available Until |
---|---|---|---|
v2.4 | /v2.4/{object} | July 8, 2015 | |
v2.3 | /v2.3/{object} | March 25, 2015 | |
v2.2 | /v2.2/{object} | October 30, 2014 | |
v2.1 | /v2.1/{object} | August 7, 2014 | |
v2.0 | /v2.0/{object} | April 30, 2014 | |
v1.0 | /{object} | April 21, 2010 | Unavailable as of April 30, 2015 |
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 theVideo
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
andexpiration_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
andDELETE /v2.4/{offer_id}
now require a Page access token withmanage_pages
andpublish_pages
permissions.GET /v2.4/{page_id}/milestones
,POST /v2.4/{milestone_id}
, andDELETE /v2.4/{milestone_id}
now require a Page access token withmanage_pages
andpublish_pages
permission.
Changes to Pages APIs
- Calls made to the
Page
nodeGET /v2.4/{page_id}/promotable_posts
now require a user access token withads_management
permission or a Page access token. - The
global_brand_parent_page
object has been renamed toglobal_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 fieldis_inline
toinclude_include
.- The maximum limit for Page related objects is now set to
limit=100
. This will impactGET
operations made on thefeed
,posts
, andpromotable_posts
edges.
Post Edit History
The edit_history
field of a Post is now available via GET /v2.4/{post_id}
.
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
andGET /v2.4/{id}/statuses
will no longer be available beginning in v2.4. As an alterantive, we suggest usingGET /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, pleasee 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 toGET /v2.4/{page_id}/promotable_posts?type=STATUS
will return an empty result set.- The
Event
node no longer supportsGET
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
, andGET /v2.4/{user_id}/notifications
operations as well asread_stream
,read_mailbox
, andmanage_notifications
permissions are deprecated in v2.4. - the
user_groups
permission has been deprecated. Developers may continue to use theuser_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.
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 theread_stream
permission. Theuser_posts
permission is automatically granted to anyone who previously hadread_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 theuser_friends
permission.
If you calling this endpoint for someone not listed in your app'sRoles 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 theratings
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 newadmin_creator
field that contains theid
andname
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
, andstart_info
.New Page Settings -
GET|POST /v2.3/{page-id}/settings
now supports four new settings:REVIEW_POSTS_BY_OTHER
,COUNTRY_RESTRICTIONS
,AGE_RESTRICTIONS
, andPROFANITY_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 byPOST /v2.3/{videolist_id}/videos
andGET
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, andscheduled_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
, andbackdated_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 withno_story
andbackdated_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 nowGameRequests
- 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 forread_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. Previouslypublish_actions
was required. People who grantedmanage_pages
andpublish_actions
before v2.3 have automatically been grantedpublish_pages
. If anyone logs in via v2.3, you'll need to requestpublish_pages
explicitly in addition tomanage_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 asPOST /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 thelocation
field without specifying thecity_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 renamedcountries
when you make aPOST|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 anaccess_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 anevent
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 asuser_interests
anduser_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 theis_hidden
orcan_hide
fields on thecomment
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 newtoken_for_business
field on theuser
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 thesigned_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 newobject
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 onPOST /{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
andlongitude
can now be specified as properties of thelocation
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 totrue
, and will clear previously specified hours inhours
field. To set specific hours, usehours
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 toAdmin
.CONTENT_CREATOR
has been renamed toEditor
.MODERATOR
has been renamed toModerator
.ADVERTISER
has been renamed toAdvertiser
.INSIGHTS_ANALYST
has been renamed toAnalyst
.
- The
settings
edge on the Page node will no longer include entries for settings where thevalue
field would be null. POST /{page_id}/settings
will no longer support thesetting
andvalue
params. Instead, you should specify theoption
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 themanage_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 theFB.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 theuser_likes
permission. Starting in v2.2, theuser_likes
permission will be required to query these endpoints. Also, we will require theuser_likes
permission on versions older than v2.2 starting 90 days from today, on Jan 28, 2015. Facebook will not grant theuser_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
andDELETE /{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
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 }
The dialogs/oauth endpoint no longer support the 'return_session' and 'session_version' parameters for legacy authentication methods.
- /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.
- 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.
- /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.
- 'uri' can no longer be requested from picture fields: Apps previously requesting
uri
should instead useurl
.
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 bypublic_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 theuser_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 ishttps://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, thestatus
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 theuser_checkins
permission./me/questions
has been removed, along with theuser_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 theuser_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 permissionuser_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
anduser_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 replacebasic_info
as the default.public_profile
contains much of the same information asbasic_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 deprecateduser_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 availableuser_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.