Released July 29, 2019 | Available until November 2, 2021 | Blog Post
This change applies to v4.0+ and will apply to all versions on October 29, 2019.
A small subset of User access tokens are no longer valid. Any API requests made using these tokens will fail. If your app has been affected, a dev alert has been sent to you. Query the /token_deprecation_check
endpoint to see if any of your User access tokens are affected. Users who's access tokens are invalidated will need to re-authenticate.
This change applies to v4.0+.
GET /{application-id}/picture
— This endpoint has been deprecated.The change applies immediately for all apps created after July 29 2019, and on August 29 2019 for all existing apps.
The user
field will no longer be included in Signed Request objects.
This change applies to v4.0+
Endpoints that return amounts in a specific country's currency now comply with the Unicode Common Locale Data Repository standard. If an endpoint returns an amount in a specific country's currency, but the calling app is outside of that country, the country's ISO country code will be prefixed to the currency's symbol. For example, if an endpoint returns amounts in US dollars but the app making the request is in Australia (which also uses the $ symbol), the endpoint will respond with US$99
instead of $99
.
This change applies to v4.0+ and will apply to all versions on October 29, 2019.
Parameters that accept User IDs will only accept app-scoped User IDs and no longer accept global User IDs unless the User is known to the app by their global ID. This applies to all endpoints.
The following change is a non-versioned features.
M.me links now reopen the 24hr window within existing threads. When a person clicks an m.me link that contains a ref parameter and is taken into an existing thread, it will now reopen the 24hr standard messaging window. This will allow apps powering Pages to reply to people based on the context that the ref parameter provides.
This change applies to v4.0+ and will apply to all versions on October 29, 2019.
Page rate limiting is now tied to the number of people a Page can send messages to.
The following features and endpoints are deprecated on v4.0+.
POST
/me/message_creatives
POST
/me/broadcast_messages
POST
/me/broadcast_reach_estimations
The following features are deprecated on v4.0+ and will be removed from all versions on October 29th, 2019.
This change applies to v4.0+ and will apply to all versions on October 29, 2019.
For an app to access the pages associated with an Instagram User or media owner, one of the following permissions is now required:
Affected endpoints include but are not limited to:
GET /{page-id}/instagram_accounts
GET /{page-id}/page_backed_instagram_accounts
This change applies to v4.0+ and will apply to all versions on October 29, 2019.
The following endpoint is deprecated:
This change applies to all versions.
Apps temporarily approved for Page Public Content Access must undergo App Review in order to continue using the feature.
This change affects v4.0+.
Starting with v4.0 we will use a whole number versioning system for Graph API releases.
This change applies to v4.0+.
The like
webhooks field for Page Feed has been deprecated. Page likes will now be delivered by the reactions
webhooks field.
This change applies to all versions.
We have implemented a number of backend changes which should significantly improve the speed and success rate of webhooks notifications, and reduce the number of duplicate notifications you may receive.
Released July 29, 2019 | Available Until March 31, 2020
In August of 2019 we will introduce Business Asset Groups. Large advertisers or agencies with large numbers of assets and users can efficiently manage their businesses with this API. Advertisers can logically group assets and users, which enables them to assign permissions at scale. See Business Asset Groups.
We will have these new GET
, POST
and DELETE
endpoints:
GET /{business_ID}/business_asset_groups
GET /{business_scoped_user_ID}/business_asset_groups
GET /{business_asset_group_ID}/assigned_users
POST /{business_asset_group_ID}/assigned_users
DELETE /{business_asset_group_ID}/assigned_users
GET /{business_asset_group_ID}/contained_pages
POST /{business_asset_group_ID}/contained_pages
DELETE /{business_asset_group_ID}/contained_pages
GET /{business_asset_group_ID}/contained_adaccounts
POST /{business_asset_group_ID}/contained_adaccounts
DELETE /{business_asset_group_ID}/contained_adaccounts
GET /{business_asset_group_ID}/contained_product_catalogs
POST /{business_asset_group_ID}/contained_product_catalogs
DELETE /{business_asset_group_ID}/contained_product_catalogs
GET /{business_asset_group_ID}/contained_instagram_accounts
POST /{business_asset_group_ID}/contained_instagram_accounts
DELETE /{business_asset_group_ID}/contained_instagram_accounts
GET /{business_asset_group_ID}/contained_pixels
POST /{business_asset_group_ID}/contained_pixels
DELETE /{business_asset_group_ID}/contained_pixels
GET /{business_asset_group_ID}/contained_offline_conversion_data_sets
POST /{business_asset_group_ID}/contained_offline_conversion_data_sets
DELETE /{business_asset_group_ID}/contained_offline_conversion_data_sets
GET /{business_asset_group_ID}/contained_applications
POST /{business_asset_group_ID}/contained_applications
DELETE /{business_asset_group_ID}/contained_applications
GET /{business_asset_group_ID}/contained_custom_conversions
POST /{business_asset_group_ID}/contained_custom_conversions
DELETE /{business_asset_group_ID}/contained_custom_conversions
In the past, ads buying could cause system timeout, out of memory errors or delays. To scale the system, we decoupled logic that requires significant computation and that causes transient errors to an separate workflow called post-processing. Now when you create or edits ads, it is more resilient to transient errors.
To represent a post processing phase after a request is received, we introduce a new ads run status IN_PROCESS
in Marketing API 4.0. This new status applies to:
{campaign_ID}
,{ad_set_ID}
,{ad_ID}
and{ad_creative_ID}
. For more information, see Using the API, Post-Processing.
We added a new run status, IN_PROCESS
which applies to ad campaigns, ad sets, ads and ad creatives. The status means Facebook is processing the ad object.
Once we finish, the ad object can be ACTIVE
or PAUSED
for campaigns, ad sets, or ad creatives, or
PENDING_REVIEW
for ads. If we find any errors during processing, we set the ad to WITH_ISSUES
.
We added a new breakdown in Facebook Ads Insights API. You can now group insights data by mobile web and mobile app. The old breakdown showed all mobile data together irrespective of whether it came from mobile web or mobile app traffic. The impacted endpoints are:
GET {adaccount_ID}/insights
,GET {campaign_ID}/insights
,GET {adset_ID}/insights
,GET {ad_ID}/insights
,POST {adaccount_ID}/insights
,POST {campaign_ID}/insights
,POST {adset_ID}/insights
,POST {ad_ID}/insights
.issues_info
Introduced a new error type to issues_info. The error type can be soft or hard. Hard errors block delivery and we set your ad to WITH_ISSUES
. Soft errors do not block ads delivery. Ad objects with this new error can be in any non-deleted ad status. The impacted endpoints are:
GET {ad_creative_ID}?fields=issues_info
,GET {ad_campaign_ID}?fields=issues_info
,GET {adset_ID}?fields=issues_info
, andGET {ad_ID}?fields=issues_info
.Updated the the rate limit for several areas under Marketing API. This includes:
Lead Ads - Updated the the rate limit on Lead Ads API for retrieving lead data. The rate limit is 200 * 24 * the number of leads created for a Facebook Page in the past 30 days. This applies to v4.0 and above. See Lead Ads.
ads_archive
- Any app can retrieve in a continuous 24-hour period: 45500 * 24 items. This applies to ads_archive
.
Insights API - You can retrieve, for each ad account, in a one-hour time period:
ads_management
- You can retrieve for each ad account in a one-hour time period:
custom_audience
- Per each ad account in a one-hour time period:
Updated the privacy policies for Instagram user and media data. To access Instagram users or media your app needs instagram_basic
, ads_read
, ads_management
or manage_pages
permissions for the ad account associated with the user or media. The affected endpoints include, but are not limited to:
POST {ad_account_ID}/adcreatives
,
POST {ad_account_ID}/ads
,
GET {ad_creative_ID}
,
GET {ad_ID}
,
GET {ad_ID}
, and
GET {ad_account_ID}/instagram_accounts
.
Beyond Marketing API, this also impacts the Pages API and APIs to access Instagram users, see Graph API Changelog, 4.0.
Renamed suggested videos in the API video_feeds
. This impacts POST {ad-account_ID}/adsets
.
Deprecated GET
for best_creative
. This impacts GET {adset_ID}?fields=best_creative
.
Renamed the campaign optimization goal REPLIES
to CONVERSATIONS
. This impacts POST {ad_account_ID}/adsets
.
Renamed the campaign optimization goal REPLIES
to CONVERSATIONS
. This impacts POST {ad_account_ID}/adsets
.
Deprecated POST
or DELETE
of /users
on ad accounts. This impacts these endpoints:
POST /{ad_account_ID}/users
DELETE /{ad_account_ID}/users
Changed the ad account level rate limit to better reflect the volume of API calls. We now compute the rate limit quota based on your Marketing API access tier and the business owning your app. This change applies to all Marketing API endpoints, such as:
GET {ad_account_ID}
GET {ad_campaign_ID}
GET {ad_set_ID}
GET {ad_ID}
GET {ad_account_ID}/customaudiences
POST {ad_account_ID}/campaigns
POST {custom_audience_id}
For more information, see Rate Limiting.
We now require business_management
permission to access the business
field on ad accounts and product catalogs. You can read this field to determine if you have permissions to the account or catalog through a particular business. This change applies to all versions on October 29th, 2019. This impacts:
GET /{user_ID}/adaccounts
GET /{user_ID}/productcatalogs
Deprecated the ad monetization property userpermissions
edge. This impacts:
GET {ad_monetization_property_ID}/userpermissions
POST {ad_monetization_property_ID}/userpermissions
DELETE {ad_monetization_property_ID}/userpermissions
Deprecated the offline conversion data set userpermissions
edge. This impacts:
GET {offline_conversion_data_set_ID}/userpermissions
POST {offline_conversion_data_set_ID}/userpermissions
DELETE {offline_conversion_data_set_ID}/userpermissions
We no longer show individual user Facebook IDs for people who are business admins when you call GET {ad_account_ID}/users
. To show business admins, use GET{ad_account_ID/assigned_users}
.
Deprecated the {app_ID}/userpermissions
edge. This impacts POST {app_ID}/userpermissions
.
Deprecated video_avg_percent_watched_actions
from the Insights API. This impacts:
GET {adaccount_ID}/insights
,GET {campaign_ID}/insights
,GET {adset_ID}/insights
,GET {ad_ID}/insights
,POST {adaccount_ID}/insights
,POST {campaign_ID}/insights
,POST {adset_ID}/insights
,POST {ad_ID}/insights
.A few reminders for our developer community:
/v4.0/
in your URLs when you call the API.