Facebook

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

May 21, 2024 By Ayyad Farah

Subscribe to Developer news

Today, we are releasing Facebook Graph API v20.0 and Marketing API v20.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

Marketing API version auto-upgrade

To enhance the overall API experience by making it more seamless and efficient, we are excited to announce the upcoming launch of the MAPI version auto upgrade feature. Starting today, we will enable the auto-version upgrade feature for Marketing API endpoints that are not affected between versions. This means between a version to be deprecated and the next available version, if an endpoint is not affected, the platform will automatically upgrade the call to the next available version, rather than directly failing the request.

To learn more about the behavior, refer to the Marketing API Versioning and the launch blog .

To check endpoints affected at each version, please refer to the changelog .

For more specific v20.0 updates, please read on.

Reminder Ads for Marketing API

Before May 13, 2024, developers could not support creating Instagram reminder ads via the Instagram Marketing API, and their customers could only create reminder ads in Meta Ads Manager. This lack of compatibility created unwanted friction for our partners and their customers who wanted to run reminder ads.

After consistently hearing feedback about this incompatibility, we are now supporting reminder ad creation via the Instagram Marketing API as of May 13, 2024.

We appreciate the feedback received from our developer community and their clients, and hope to continue improving the reminder ads experience available via Marketing API.

About Instagram reminder ads

Instagram reminder ads help advertisers bridge the gap between promotion and launch time by encouraging people interested to set reminders. People who opt in receive reminders when it matters most before the event.

About creating and editing events

Instagram reminder ads use event start time and date to determine when reminders are delivered. This change allows developers to create and edit events in the Instagram Graph API. You can create reminder ads via Instagram Marketing API after attaching events to ad creative.

New API on the Ad Account Node

The new Ad Account Node update is not a breaking change; it’s an API addition. Calling it lists all the campaigns under that ad account which have guidance recommendations, along with the guidance and the expected improvement in Cost Per Action (CPA).

The new API will allow advertisers to view Meta’s guidance on their campaigns. This data already exists on the Partner Center for all partners. However, it is available through the UI requiring manual selection of a single ad account to view the guidance.

By automating the access of this data via the CPA_GUIDANCE API, we hope to take away the manual work required to check the guidance per ad account. For our partners, access to this API will allow them to build custom views internally and see the trends overtime.

If your business manages hundreds, or thousands of accounts, it’s difficult to check any metric on them one by one, especially when it’s time sensitive (RSS recommendations updates everyday and considers active campaigns in the last 28 days). This API will enable agencies to identify the most promising campaigns that can be optimized using the provided recommendations, which will subsequently be incorporated into their systems.

The CPA_GUIDANCE API specifically enables agencies to provide guidance to their brand partners on which products or categories have the highest cost per acquisition (CPA). By sharing this information, agencies can help their brand partners optimize their ad spend and improve the overall performance of their collaborative campaigns.

Agencies will also be able to track if a guidance recommendation was actioned by observing an improving trend of CPA.

Multi-advertiser Ads

Today, we are introducing the ability for advertisers to opt in to multi-advertiser ads via the Marketing API. Prior to this update, developers could not support creating multi-advertiser ads via the API, and their customers could only opt in to multi-advertiser ads in Meta Ads Manager.

About multi-advertiser ads

Multi-advertiser ads can help people discover products and services from multiple businesses. For select placements on Facebook and Instagram, ads can appear alongside other ads in the same ad unit to help people discover products and services from businesses that are personalized to them. An ad unit is a container that displays multiple ads, usually on the same page. Learn more in the Business Help Center .

What this means for developers

At the time of launch, delivery for multi-advertiser ads created through the Marketing API is off by default, meaning developers will need to implement code changes for their customers’ ads to be eligible to deliver in the experience. Multi-advertiser ads creation is supported in all versions of the Marketing API, but all ad creation requests that are eligible for multi-advertiser ads must specify if the ad opts in to use it or not. On August 19,2024, multi-advertiser ads will change to default-on and developers who have not already implemented code changes will need to do so in order to provide their customers with the ability to opt out of the experience.

Generative AI creative features coming to Marketing API: Text Generation, Image Expansion and Background Generation

In October 2023, we announced the launch of our first generative AI-powered creative ad features - Text Generation , Image Expansion and Background Generation - to businesses in Ads Manager. Today, we wanted to make you aware that we are bringing these generative AI creative features to advertisers via our Marketing API (MAPI) so partners, agencies and advertisers can also take advantage of Meta’s GenAI offerings through MAPI.

These features enable the generation of creative variations quickly and automatically, unlocking a new era of creativity that maximizes the productivity, customization, and performance for all advertisers:

Background Generation : Creates up to four backgrounds to complement product images, enabling creative diversification for your audiences. The backgrounds generated will be based on your original product images and are often simple backgrounds with colors and patterns.
Image Expansion : Seamlessly adjusts image creative assets to fit different aspect ratios across surfaces, starting with Feed and soon expanding to Reels, allowing you to spend less time and resources on repurposing creative assets.
Text Generation : Generates multiple versions of ad texts based on your original copy, highlighting the selling points of products/services and generating multiple text options to diversify your ads for audiences.

Today we're bringing these features to more advertisers, we’re pleased to give the power of our generative AI to a broader audience.

In line with our approach for testing new products that may be subject to additional scrutiny, certain industry verticals such as Financial Services and Pharma/Health and ads for Housing, Employment or Financial Services/Credit(HEC), Social Issues, Elections, or Politics (SIEP) may not have immediate access to all generative AI features.

How will it work?

Today, we are rolling out support for these features as part of our Marketing API, more specifically the Ad Creative APIs. Advertisers will have the ability to opt in to use these features from the API as well as preview Generative AI creatives from the API.

The following example shows how to opt in your ad creative into Generative AI features on Marketing API.

curl -X POST \
          -F 'name=Generative AI Creative' \
          -F 'object_story_spec={
          ...
          }' \
          -F 'degrees_of_freedom_spec={
          "creative_features_spec": {
          "image_background_gen": {
          "enroll_status": "OPT_IN"
          }
          }
          }' \
          -F 'access_token=<ACCESS_TOKEN>'\
          https://graph.facebook.com/<GRAPH_API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Note : The example above shows Opt-in for Background Generation feature. Similarly for Image Expansion use the image_uncrop key and for Text Generation use text_generation key in the creative_features_spec .

Advertisers will also be able to preview Generative AI transformed creatives through the API. Please follow the developer documentation link to learn more about how to generate, provide the ad creative, and preview the generated content for each of our GenAI features.

Instagram Video API: Resumable Upload for Instagram Video API

Started on May 15th, 2024, the new “Resumable Upload Protocol” will support the publishing of Instagram videos (i.e., Reels, Video Stories, and Video Carousel) from both local videos and public hosted url videos. This new protocol allows for local file uploads, longer video uploads for only Reels (i.e., up to 15 minutes), and resuming an upload operation after a network interruption or other transmission failure.

Previously to create Instagram videos, the video files had to be uploaded to a publicly accessible hosting service, where a shareable URL would be obtained and provided to Meta in order to publish the video.

The improved content publishing flow details can be found in the content publishing developer documentation with additional details around Instagram media found here .

Instagram Graph API: Onboarding New Metrics

Today, six additional metrics for Carousel Container Media will be made available for the Graph API. These metrics are Likes, Comments, Shares, Follows, Profile Activity (i.e., number of actions taken when a user visits your profile), Profile Visits (i.e., number of times your profile was visited). These metrics have already been available in Instagram’s Insights Page, but this will ensure that they are available as well via the Graph API.

By adding Likes, Comments, Shares, Follows, Profile Activity, Profile Visits to the Graph API endpoints for Carousel Posts, you should be able to read these metrics directly from the API Call.

Please reference the full list of these metrics here in order to add the relevant metrics to your GET API Call for carousel container posts today.

Updated Deprecation Timeline: Meta’s Offline Conversion API (OCAPI)

Last year, we announced that Offline Conversions API version 17 will no longer support offline events and that we anticipated that the Offline Conversions API would be discontinued in the third quarter of 2024. This anticipated deprecation timeline has since been updated and we are confirming that the Offline Conversions API (OCAPI) will be deprecated in May 2025 . Although the deprecation of OCAPI has been extended from Q3 2024 to May 2025 , we still encourage advertisers who are currently sending offline events via Offline Conversions API (OCAPI), to continue to plan to migrate their existing set up to start sending offline events through the Conversions API (CAPI for Offline).

Deprecations & Breaking Changes

Discontinuation of the Booking Button in Messenger API

Effective immediately, the Booking button will no longer be supported in Messenger API calls. This change does not affect other templates and buttons, and businesses can still manage bookings using Meta Business Suite.

Discontinuation of Sponsored Messages Ad Type creation in Marketing API

As of today, the creation of the Sponsored Messages ad type will no longer be available in Marketing API v20.0 and ad creation support for this ad type from previous versions of the API will end after 90 days. This change will not affect other messaging ads ad types.

We recommend reviewing current integrations and adjusting applications as necessary to ensure a smooth transition for users.

Removal of Non-Critical Timeframes for Insights Demographics Metrics (via External Instagram Graph API)

On May 21, 2024 , we rolled out Version 20 of the Instagram Graph API.

After 90 days of this launch (i.e. August 19, 2024), the Graph API will no longer share demographic metrics on audience members engaged and reached within non-critical time frames for the Instagram Graph API (e.g., countries, cities, age, and gender distribution information over the last 14 and 90 days).

The Instagram Graph API will still return demographic information for the past month (i.e., “this_month”) and past week (i.e., “this_week”), similar to that of the Instagram app in order to ensure consistency across the platforms.

This new upgrade reduces any confusion as well as increases the reliability and quality of our reporting.

Please review the developer documentation to learn more.

API Version Deprecations:

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

Graph API

May 28, 2024: Graph API v13.0 will be deprecated and removed from the platform.
September 17, 2024: Graph API v14.0 will be deprecated and removed from the platform.
November 20, 2024: Graph API v15.0 will be deprecated and removed from the platform.

Marketing API

Aug 13, 2024: Marketing API v18.0 will be deprecated and removed from the platform.
Feb 4, 2025: Marketing API v19.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.

Meta Business SDK

Meta Business SDK v20 Release

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

In this release, we are also introducing additional support for Instagram APIs. These are IGMediaForIGOnlyAPI, IGUserForIGOnlyAPI, IGRefreshAccessTokenForIGOnlyAPI, and IGAccessTokenForIGOnlyAPI. They enable more methods on top of the existing Instagram APIs that allow you to fetch media directly. We aim to onboard more APIs that cover other Meta products to enrich the ecosystem of the Business SDK.

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