Introducing Facebook Graph API v12.0 and Marketing API v12.0

Today, we are releasing Facebook Graph API v12.0 and Marketing API v12.0. Below, we’ve highlighted changes that will impact parts of our developer community. These changes include announcements and product updates, reminders from prior launches, and notifications on large-scale deprecations that may affect your application(s)’ integration with our platform.

For a complete list of all changes and their details, please visit our changelog.

General Announcements and Updates

Conversions API: Expanding minimum callable version

Graph API Backwards Compatibility for Apps Created with One-Click Access Tokens  Beginning with v12.0, newly created access tokens generated under the Conversions API settings tab in Events Manager are now supported by all available Graph API versions (see the supported versions here).

Please note that calls made with these tokens to a deprecated Graph API version will automatically resolve to the oldest available version. This behavior only applies to Graph API endpoints. Marketing API endpoints, including the Conversions API, do not support auto-upgrade behavior and will throw an exception.

User Profile API for Instagram Messaging: New fields

We are making enhancements to the User Profile API for Instagram messaging. Previously, User Profile API for Instagram supported two fields: 1) Name and 2) URL of the profile picture. In order to allow businesses to better personalize and prioritize messages based on publicly available user information, we have updated the API to also include following information:

1. Follower count
2. Verified Badge
3. Business follows User account [Yes/No]
4. User account follows Business account [Yes/No]

Please refer to the developer documentation for details.

Detailed Targeting New Opportunities

To help advertisers find additional opportunities that weren’t originally available to them, when advertisers leverage Detailed Targeting and optimize for conversions, value or app events using the conversions objective they will be automatically included into Targeting Expansion. For more information please refer to the Detailed Targeting Expansion Help Center article.

Video API: New fields

We have added two new fields, views and post_views, to the [Video] node. Please view the Video API developer documentation to learn more.

Deprecations & Breaking Changes

Error Transparency

The Graph API and Marketing API default behavior is to throw an error when an app requests a field or edge on a node that returns an associated node or nodes, but lacks the appropriate permissions required by the associated nodes. However, a number of these fields and edges did not follow this protocol and instead were simply omitted from API responses if the calling app lacked appropriate permissions.

Starting with v12.0 these fields and edges will conform to the default behavior. This change will apply to all versions on December 13, 2021.

• Affected Graph API endpoints
• Affected Marketing API endpoints

System users and app roles

We are deprecating the ability for system users to be granted roles on apps unless the users and the apps both belong to the same businesses. In order to prevent disruption to your app and business, we recommend that these system users be removed from your app and use the Business On Behalf Of API instead. This breaking change will go into effect on December 13, 2021.

Scheduled Live

UPDATE: This deprecation has been delayed.

We are deprecating the planned_start_time parameter within the Scheduling capability in the Live API and the breaking change will go into effect on December 13, 2021. A new parameter will be announced at a future date.

Messenger Platform: Conversation API

We are deprecating the user_id field from the thread metadata in Conversation API. All developers will need to migrate any references to user_id (IGID) and fully rely on IGSID as a primary identifier of a thread between the user and business.

This breaking change will go into effect on prior Graph API versions on December 13, 2021. Please view the Conversation API developer documentation to learn more.

Messenger Platform: Instagram Webhooks

We are making an update to our Messenger API for IG reaction webhook in order to better support emoji reactions. The current version returns the emoji field as a string - with this update, reaction webhooks will return a new unicode format. Note that the “reaction” field will only support the default emojis. For all other emojis the reaction field will return “other,” the same as MSGR.

This breaking change will go into effect on prior Graph API versions beginning December 13, 2021. In order to continue to support emoji reactions, all developers need to migrate to the new unicode we are returning by December 13, 2021. Please refer to the Webhook developer documentation for details.

API Version Deprecations:

As part of Facebook’s versioning schedule for Graph API and Marketing API, please note the upcoming deprecations:

Graph API

• November 2, 2021: Graph API v4.0 will be deprecated and removed from the platform
• February 3, 2022: Graph API v5.0 will be deprecated and removed from the platform
• May 22, 2022: Graph API v6.0 will be deprecated and removed from the platform

To avoid disruption to your business, we recommend migrating all calls to the latest API version that launched today.

Marketing API

• Marketing API v10.0 will deprecate on 10/04/2021
• Marketing API v11.0 will deprecate on 02/23/2022

To avoid disruption to your business, we recommend migrating all calls to the latest Marketing API version that launched today. (Visit the changelog for more details).

Facebook Platform SDK

• On January 19, 2021, we announced the 2-year deprecation schedule for Facebook Platform SDK v8.x and below. These versions will sunset in January of 2023.
• On June 8, 2021, we released Facebook Platform SDK v11.0, which began the 2-year deprecation of Facebook Platform SDK v9.0. SDK v9.0 will sunset in June of 2023.

General Deprecations

Native Offers Endpoint Deprecation

On June 8, 2021, we announced the deprecation of Offers Ads API. This will go into effect immediately with the release of Graph API v12.0.

Messenger Platform - Airline Templates

On June 8, 2021, we announced the deprecation of airline templates. This will go into effect on December 6, 2021.