Introducing Graph API v21.0 and Marketing API v21.0

Today, we are releasing Graph API v21.0 and Marketing API v21.0. As part of this release, we are highlighting changes below that we believe are relevant to parts of our developer community. These changes include announcements, product updates, and notifications on deprecations on relevant application(s) integrations with our platform.

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

General Updates

Image Expansion Merging With Standard Enhancements

Applies to 'v21.0+'

For single media ads, the Image Expansion feature will be included as part of Standard Enhancements. Therefore, if creating an ad or creative opted-in to Image Expansion, please refer to the following link for instructions to set standard_enhancements as a field inside the creative_features_spec.

The following endpoints are affected:

• POST /{ad_account_id}/adcreatives
• POST /{ad_account_id}/ads
• GET /{ad_id}/previews
• GET /{ad_account_id}/generatepreviews

Deprecations & Breaking Changes

Deprecate: package_name / signature_hash params for OTP buttons on Authentication Message Templates

Starting with v21.0, when creating WhatsApp one-tap autofill or zero-tap authentication templates, package_name and signature_hash will no longer be accepted as button object properties. Instead, these must be defined as properties of a "supported app" object within the supported_apps button property array. The supported_apps property was added in a previous release to support single or multiple package/hash definitions.

Deprecate: Messaging Events API

• Messaging Events API will be deprecated in September 2025. To prepare for this deprecation, Messaging Events API will no longer be supported in any future releases of Graph API, starting with version 21.0.
• Partners can still send events through Conversion API which is our new solution and can learn more about it here.
• Partners who choose not to update to the latest Graph API will still be able to access Messaging Events API by calling Graph API version 20.0 or prior until the official product deprecation in September 2025. At that time, Partners will need to be sending all events via Conversions API.

Instagram Insights API: Metric Deprecation

On October 02, 2024, we rolled out version 21 of Instagram Insights API.

To improve metric quality as well as continue aligning the functionality of Instagram API with that of the Instagram app, the following metrics will be deprecated starting version 21:

• video_views (total value): total number of views by video
• email_contacts (time series): number of email contacts over a specified period of time
• get_directions_clicks (time series): number of taps on the directions link in the IG user profile number of email contacts over a specified period of time
• profile_views (time series): number of users who have viewed the IG User's profile over a specified period of time
• text_message_clicks (time series): number of taps on the text message link in the IG User's profile over a specified period of time
• website_clicks (time series): number of website visits over a specified period of time
• phone_call_clicks (time series): number of phone call clicks over a specified period of time

We will continue to support total value metrics on the Instagram Insights API for those that are also available in the Instagram app. Supported metrics can be viewed here. Please migrate the usage accordingly by January 8th, 2025 to avoid suboptimal experience to your application.

WhatsApp Cloud API Local Storage

Applies to 'v21.0+'

The upcoming changes to the WhatsApp Cloud API platform involve a significant update to the local storage settings for the Cloud API. The ability to enable local storage will now be integrated into the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings endpoint. This adjustment allows the setting to be configured before a phone number is registered, enhancing the setup process's flexibility and control. Additionally, the current setting can be verified through the GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/settings endpoint to confirm that the local storage is correctly set to the intended country prior to the phone number registration.

It's important to note that updates to the local storage settings will only be permissible for phone numbers that have not yet been registered. A registered phone number needs to be deregistered before changing the setting. This change aims to ensure the data is always stored in the intended country.

• POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/ register
• POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/ settings

Marketing API v21 impacts on original objective usage

V21 of the Marketing API will be released on October 2, 2024. With this new version comes further limitations on the use of original (legacy) objectives.

What is changing?

While existing campaigns using the original objectives can continue to run, beginning with v21, you can no longer create new ad sets or ads within these original objective campaigns.

Impacted APIs:

/act_{ad_account_id}/campaigns

/act_{ad_account_id}/ads

How do I know if I’m using original or simplified objectives?

You can refer to this post to refresh your understanding of our campaign objective simplification, which initially began in 2021.

Please note, there are two objectives that remained exactly the same through the objective changes: traffic and app installs (now called ‘app promotion’). Therefore, new ads and ad sets can still be created under these campaigns.

Do I need to take any action at this time?

As we continue to limit the usage of the original objectives with each API version, we encourage you to transition all your campaigns to the simplified objectives.

Meta Business SDK

Meta Business SDK v21 Release

The Meta Business SDK v21 release will be published shortly after the release of Graph API v21. This release will include bug fixes, dependency upgrades, new features, and most importantly, an updated API interface to match Graph API v21.

In this release, we also aim to provide sample code for additional scenarios. These files are available in all five languages and cover more than 30 scenarios. We hope this will greatly enhance the onboarding experience while offering richer guidance to support your integration with the Business SDK.

As part of our 2-year deprecation schedule for Platform SDKs, please note the upcoming deprecations and sunsets:

• May 2025: Facebook Platform SDK v17.0 or below will be deprecated.

API Version Deprecations:

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

Graph API

• November 20, 2024: Graph API v.15 will be deprecated and removed from the platform
• May 14, 2025: Graph API v.16 will be deprecated and removed from the platform

Marketing API

• Feb 4, 2025: Marketing API v19.0 will be deprecated and removed from the platform
• May 6, 2025: Marketing API v20.0 will be deprecated and removed from the platform

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