What’s New with Facebook Graph API and Marketing API Version 12.0

September 17, 2021

Please see the latest article on Facebook Graph API v13.0 and Marketing API v13.0.

On September 14th, 2021 Facebook released their latest Graph API version 12.0 and Marketing API version 12.0. When Facebook releases an update to their social media APIs, it is important to pay attention since they often contain new features, major bug fixes, or breaking changes. Here is what is new with the APIs.

Overall, this isn’t that big of a release, but it is good to review and make sure nothing in your app breaks or there are new features you can introduce for you users.

These are the major changes with the APIs v12.0:

Graph API Changes

Instagram Messaging API: New User Profile Fields

New fields have been added to the GET /{ig-scope-id} Instagram Messaging API endpoint:

  • is_verified_user: Boolean value if user is verified.
  • follower_count: Int value of count of followers.
  • is_user_follow_business: Boolean value if the user follows the business or not.
  • is_business_follow_user: Boolean value if the business follows the user or not.

Facebook continues to expand their Instagram capabilities since introducing the Instagram Publishing API in January, 2021. We hope to see further expansion in the future.

Live Video API and Video API

This one is a bummer since Facebook has deprecated live video scheduling in the Live Video API. The planned_start_time parameter for the POST /ID/live_videos will now return an error starting December 13, 2021. Facebook promises that “a new parameter will be announced at a future date.”

On the bright side, the Video API /{video-id} endpoint introduces two new useful fields:

  • post_views: Int value of the public view count of the video post, not aggregated with any other crossposts of the video.
  • views: Int value of the public view count of the video.

Graph API Endpoints Now Throw the Right Errors

By default if you don’t have permissions to an endpoint an error should be thrown. However, not all endpoints did this. In fact, some ignored your request if you didn’t have permissions, which makes debugging very difficult.

Now most endpoint properly return an error if you don’t have permissions. For example:

See here for the complete list.

App Insights API is Deprecated

Put simply, the App Insights API is deprecated. Specifically the endpoint: GET /{application-id}/app_insights

Marketing API Changes

Targeting Expansion

Targeting expansion helps improve your campaign performance by allowing ads to reach a broader group of people then defined in your detailed targeting selections. You can learn more about targeting expansion here.

For this Facebook API version 12.0 update, your ads will automatically be added to the target expansion if you’re optimizing for conversions. As Facebook says:

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.

This is overall a positive change, but slightly dangerous if you don’t want to have targeted expansion and are unaware you were added.

Business Management API: System Users and App Roles

Starting December 13th, 2021,  a system user can now only be granted a role on an app if both the system user and the app belong to the same business. This could break something in your system, so Facebook recommends you remove the system users from your app and instead use the Business On Behalf Of API.

Endpoints Now Throw the Right Errors

As was done for the Graph API errors, the Marketing API endpoints properly return an error if you don’t have permissions.

For example:

  • GET /{business-id}/client_ad_accounts
  • GET /{hotel-id}/videos_metadata
  • GET /{product-catalog-id}/services

See here for the complete list.

Additional API Changes

  • Conversation API: The user_id is deprecated and you must rely on the IGSID as a primary identifier.
  • Instagram Webhooks: Emoji reactions now return as unicode instead as a string.
  • Catalog API: The review_status field on the Product Item node is deprecated.

Previous Facebook API Versions

Finally, if you’re using older versions of the Facebook Graph API, some will be deprecated in coming months:

Graph API Deprecation Schedule

  • November 2, 2021: v4.0.
  • February 3, 2022: v5.0.
  • May 22, 2022: v6.0.

Marketing API Deprecation Schedule

  • October 4, 2021: v10.0.
  • February 23, 2022: v11.0.