Back to News for Developers

Introducing Graph API v4.0, Marketing API v4.0

July 29, 2019ByKyle Minshall

We've released the newest versions of Graph API (v4.0) and Marketing API (v4.0). The changes include improvements to managing business assets, ad creation, and Facebook Ad Insights. We're also announcing updates to Messenger API and the Facebook SDK and improvements to rate limiting.

Starting with this release, the Graph API will be transitioning to using major numbers for all new versions. The next version number will be v5.0 (instead of v4.1); the one after that will be v6.0; and so on. This change in numbering will align the version numbers of our SDKs with the version of the API.

Graph API (v4.0)

These changes apply to Graph API v4.0. For a full list of the Graph API v4.0 updates, please read the Graph API v4.0 changelog. Be sure to check how much longer we will be supporting the version of the Graph API you are currently running.

  • Pages API: For an app to access the pages associated with an Instagram User or media owner, one of the following permissions is now required:
  • Page Public Content Access: Apps temporarily approved for Page Public Content Access must undergo App Review in order to continue using the feature.
  • Webhooks
    • Page Feed
      The like webhooks field for Page Feed has been deprecated. Page likes will now be delivered by the reactions webhooks field.
    • Performance Improvements
      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.

Marketing API (v4.0)

The following updates apply to Marketing API (v4.0). For a full list of changes, see the Marketing API (v4.0) changelog.

  • Business Asset Groups:
    Starting on August 14, advertisers will be able to use this feature in the Marketing API to better group Facebook assets and manage permissions to these assets. More documentation on this new product will be available on August 14.
  • Improvements to Ad Creation and Edits:
    We’ve improved post processing so that ads creation and editing is more resilient to transient errors. After a request is received, there is a new ads run status IN_PROCESS which means Facebook is processing the ad object. This new status applies to ad campaigns, ad sets, ads, and ad creatives. After processing, the ad object can be ACTIVE, PAUSED, or PENDING_REVIEW. If there are errors, we set the ad to WITH_ISSUES. Please refer to the Marketing API documentation for more details.
  • New Breakdown in Ad Insights by Mobile Web & Mobile App
    You can now group insights data by mobile web and mobile app. Previously, insights showed all mobile data together regardless of whether it came from mobile web or mobile app traffic. Visit the Marketing API (v4.0) changelog to see the affected endpoints.
  • New Error in issues_info
    We’ve 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. Visit the Marketing API (v4.0) changelog to see the affected endpoints.

Additional Marketing API updates:

  • Ads Management Updates:
    We’ve updated the policies for Instagram users 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. Note that beyond the Marketing API, this also impacts the Pages API and APIs to access Instagram users. See the Marketing API (v4.0) changelog or specific endpoints that are affected.
  • Deprecated or Renamed APIs:
    A number of APIs have been renamed or deprecated. See the Marketing (v4.0) API changelog for more details on these breaking changes.
  • Rate Limits Updates:
    We’ve updated the the rate limit for several areas under Marketing API including Lead Ads API, Insights API, and more. We’ve also 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. For more information, see our documentation on rate limiting.
  • Business Management Permission Updates:
    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. See the Marketing API (v4.0) changelog for specific endpoints that are affected.

Messenger API (v4.0)

The following updates apply to Messenger (v4.0).

  • Deprecated Features: As announced on June 10, certain features are not going to be incorporated into the new version of Messenger. As part of the v4.0 release, we are reflecting those changes into the API. The following features will be deprecated starting v4.0:
    • Location Quick Reply Button - deprecated for all versions on October 29, 2019
    • Share Button - deprecated for all versions on October 29, 2019
    • Messenger Codes - deprecated for all versions on October 29, 2019
    • Vertical List Template
    • Open Graph Template
  • Broadcast API deprecation: Beginning with v4.0, we are also deprecating Broadcast API. We recommend apps and Pages that have access to subscription messaging to use the Send API with the NON_PROMOTIONAL_SUBSCRIPTION message tag to achieve the same outcome. deprecated in v4.0:
    • broadcast_messages
    • broadcast_reach_estimations
  • links now open the 24hr window within existing threads: When a person clicks or scans an link that contains a ref parameter and is taken into an existing thread, it will now open the 24hr standard messaging window. This will allow apps powering Pages to reply to people based on the context that the ref parameter provides.

Updates to Facebook SDK, Rate Limiting and Signed Request:

  • Avoid iOS Facebook Login Issues with Facebook SDK 5.2.3: The new version of the Facebook SDK will help ensure your app's Facebook Login integration does not run into issues once iOS 13 is launched. This SDK update will help maintain a positive experience and login rate for your potential customers. Learn more about this important update in our changelog.
  • Rate Limiting Updates: We’re launching new rate limits for custom audiences, ads management, lead generation and Messenger. These limits better reflect the actual volume of API calls needed. These changes add the new rate limits we announced earlier this year for page management, ad insights and Instagram Business.
    • Custom audiences: The new rate limit is now tied to the number of an ad account’s active custom audiences.
    • Ads management: The new rate limit is now tied to the number of the ad account’s active ad groups.
    • Lead generation: The new rate limit is now tied to the number of lead forms created for a Facebook Page.
    • Messenger: The new rate limit is now tied to the number of people a Page can send messages to.

      These changes apply to v4.0+. For more information, visit Rate Limiting on the Graph API.
  • Changes to Signed Request for web games on
    The "user" field will no longer be included in Signed Request object. The change applies immediately for all apps created after July 29, 2019, and on August 29, 2019 for all existing apps.

A few reminders for our developer community: