Migration Guide: MBE, v2 to MBE, v3

This guide describes the changes required to migrate existing Business apps on Meta Business Extension (MBE, v2) to be compatible with MBE, v3. Going forward, MBE will require these updates and is not backwards-compatible with the next version of the Graph API.

Key Benefits of MBE, v3

With MBE v3, third-party app developers can:

1. Offer businesses simpler onboarding flows.

2. Help reduce churn.

3. Allow businesses to flexibly manage the features they want to enable for each Business app. For example, an online seller can initially set up messaging features with a business app, and later choose to enable their Facebook Shop with the same app. This is a great way to upsell businesses on multiple FBE features.

4. Accommodate multiple business types in their integration with FBE. For example, a third-party app can offer one type of integration to a subset of businesses that only require advertiser tools, and separately offer another type of integration for businesses that only require messaging tools.

Before You Begin

Ensure your Meta partner manager is aware you are making this upgrade so they can properly support you if you need help.

Overview

Terminology

Feature: A particular integration that can provide outcomes for your businesses. Each integration has unique implementation requirements, and you can set which features you want to enable. Examples can include page_cta, chat_plugin, and so on. For a complete list, see this Feature list.

Vertical: Represents the type of business. You can integrate with one or more vertical, depending on the type of businesses you serve. A single business can also be set up on one or more verticals, depending on their needs. For a complete list, see this Verticals List.

Intent: An Intent is the MBE name for a particular use case. For example, the CATALOG_ADS intent is the name for the use case that allows your app to run catalog ads, to sync and promote your catalog's products and services. Intents appear on the feature menu and map to a set of multiple features that the business gets.

Intents using v3 are similar to “channel” from v2. Configuring an intent in your login flow is not required, but doing so will prompt your merchants or advertisers to complete onboarding to the specified intent prior to seeing the rest of the available intents in the feature menu. Leaving the intent out of your login flow will show merchants or advertisers the feature menu of all available intents for your vertical, and allows them to select their own intents at the start of MBE.

For a complete list, see this Intents list by Vertical.

Key Differences between v2 and v3

MBE, v3 introduces more granularity and controls over what features a business can enable during onboarding. As a result, we are upgrading our UI and changing our webhook and API responses to reflect this level of feature detail.

Based on the features you choose to enable and the vertical you pass in for the business, MBE displays a feature menu within the onboarding flow where the business can select the features they want to install. The business can then manage these features in Management view and add more by re-entering the flow on your surface or through the Management view surface.

Recommendations

Because the set of features a business enables is dynamic and optional, we recommend that you build a framework for record-keeping. For each business:

1. Keep a list of features that have been enabled and their associated assets.
2. Synchronize with the Meta APIs to ensure this record of what features are enabled is updated and accurate.

Requirements

MBE, v3 allows a business user to:

• Opt-in to the subset of your app’s features that are relevant to them

• Add or remove features over time, independently of other features

As a result, the app integration needs to:

1. Listen for updates. A webhook will be sent every time a business goes through the flow or updates business-enabled features.

2. Once a webhook is received, check what features have been enabled by calling the FBE Installation API. Each time a business goes through the flow, they can enable or disable features.

3. Within your platform, update the record of features that have been enabled for this business.

4. Enable each feature based on the partner implementation details in the Feature List. For example, if you have enabled multiple features that require their own separate catalog, you must maintain the sync for each catalog. Pull from the Feature Configuration API if additional feature information is needed.

Your app should not assume that all assets your app supports will be returned. For example:

• A business that sets up a Shop can also do so with just their Instagram account. Therefore, your app should not require businesses to set up a Page to enable this feature.

• A business that sets up a Conversions feed to improve ad performance can do so without setting up a Page or Instagram call-to-action (CTA) button. Your app should not require a business to set up a Page or Instagram account to enable this feature.

Update Your Integration to v3

This section explains how to update your integration with the required changes for MBE, v3. As MBE, v3 is fundamentally different from MBE, v2, we recommend following these implementation guidelines to reduce potential interruptions for users.

Step 1: Set Up Features and Respond to Updates

• Update Webhook flows: Listen for webhooks that indicate that a business has updated the set of features they want to enable.

• Update integration with the FBE Installation API: Understand what features the business has enabled by calling the FBE Installation API and updating your records.

• Update integration with the Feature Configuration API: Configure each feature, and call the Feature Configuration API to pull additional info for each feature where needed.

Step 2: Configure App-Supported Features

The features that display for your merchants in the feature menu are those that you configure within the MBE Developer Panel.

Step 3: Configure Verticals

When configuring verticals, be sure to send the appropriate vertical for each business in the extras configuration under business_vertical. For example, if it’s a hair salon, send ‘APPOINTMENTS’. If it’s a Shop that sells products, send ‘ECOMMERCE'.

If a business belongs to more than one vertical, send different verticals for each entrypoint on your surface (depending on what goal the business is trying to achieve). For example, if a hair salon offers both appointments and sells hair products, you can send ‘APPOINTMENTS’ from entrypoint 1 and ‘ECOMMERCE’ from entrypoint 2. Each entrypoint will need to have their own vertical-specific features configured to work properly.

A merchant or advertiser that goes through both verticals for onboarding will be “locked in” to the same Business Manager for each vertical, if the same external_id is used. Assets (Page, pixel, catalog) from the first vertical that a merchant onboarded with will be preselected in the second vertical, but a merchant will have the option to select different assets for their second vertical. All features installed by the merchant can be read on the Feature Configuration API.

Step 4: UI Changes

The updated onboarding flow (minimal onboarding) shows a ‘feature menu’ that displays a list of intents which are bundles of one or more features that you have enabled for your businesses. Businesses can select which intents they want to install. If you would like your business to install a particular intent first and then see the feature menu, pass in an intent param in the setup object. You can choose from the intents list for this parameter. If you want to perform an experiment around the UI update or don’t want this new updated UI, the parameter use_minimal_onboarding, in the flow_config object determines which UI to show. Use_minimal_onboarding set to false will maintain the MBE v2 UI.

Step 5: Management View

Management View with v3 surfaces all the features that the business has installed and links out to install even more features. The link to Management View has been updated to be:

<a href=”https://business.facebook.com/latest/business_app_store/manage_external_business_connection?asset_id=<page_id>&business_id=<business_id>&app_id=<app_id>&external_business_id=<external_business_id>"><button>Launch Management View</button></a>

Step 6: Enable Feature Changes

To enable these feature changes, the following APIs have been updated:

Updates to the Webhook

A webhook is sent for every install and uninstall and only consists of the features the business has installed.

For uninstalls, a webhook is also sent with a response consisting only of installed features (for example, not including the uninstalled features). Each time a webhook is sent, pull from the FBE Installation API for the source of truth.

Response

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    instagram_profiles": [
"<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            “additional_info”: {
               “onsite_commerce_eligible”: bool
            }
        }
    
  }]
}

Response Fields

Updates to the FBE Installation API

The updated API model sends the list of each feature the business has enabled and the connected assets for each feature. The main change is the addition of the installed_features field. This payload is the same as the Webhook response.

After receiving the webhook, follow these recommended steps:

1. Call the FBE Installation API with the received external business ID and access token. This API contains the source of truth for installed features and their connected assets. Keep a proper record of these feature configurations.

2. Enable these features for that business (specifics on what “enabling” means are in the feature list table), and pull any additional needed information about the features from the Feature Configuration API.

The following code sample shows an example request to the FBE Installation API and the corresponding API response. Within the response, the additional v3 fields are highlighted.

Request

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/fbe_installs?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Response

{
  "data": [{
    "ad_account_id": "<ad_account_id>",
    "business_manager_id": "<business_manager_id>",
    "catalog_id": "<catalog_id>",
    "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
    "onsite_eligible": true,
    "profiles": [
      "<page_id>",
      "<instagram_profile_id>"
    ],
    "pages": [
      "<page_id>"
    ],
    "instagram_profiles": [
      "<instagram_profile_id>"
    ],
    "pixel_id": "<pixel_id>",
    "token_type": "<token_type>",
<!--UPDATES BELOW-->
    "installed_features": [
        {
            "feature_instance_id": "<unique_id>",
            “feature_name” : string, 
            "feature_type": enum,
            "connected_assets": {
                “ad_account_id”: "<ad_account_id>",
                “business_manager_id”: "<business_manager_id>",
                “catalog_id”: "<catalog_id>",
                “commerce_merchant_settings_id”: "<commerce_merchant_settings_id>",
                “ig_profile_id”: "<instagram_profile_id>"               
                "page_id": "<page_id>",
                "pixel_id": "<pixel_id>",
            },
            “additional_info”: {
               “onsite_commerce_eligible”: bool
            }
        }
    ]
  }]
}

Updates to the Feature Configuration API Response

The updated model includes the feature instance ID for each feature and new fields that consist of an array of all features of that type installed by that business (example: multiple page CTAs).

For the non-customizable features described in the feature list, only a feature instance ID and an enabled flag displays. You can update only the customizable features with a POST request.

This model is different from the FBE Installation API because it provides additional feature information beyond the connected assets, including enabled status and specific feature customizations. After calling the FBE Installation API, use this API if more information is needed about the feature’s enabled status or configurations.

Read

You can read the current feature configuration status of any business with the following request:

CURL -X GET 
'https://graph.facebook.com/<API_VERSION>/fbe_business/?fbe_external_business_id=<fbe_external_business_id>&access_token=<access_token>'

Update

To update all features, use the following POST request:

CURL -i -X POST \   
  -F 'fbe_external_business_id=<fbe_external_business_id>' \
  -F 'business_config={business_config object}' \
  -F 'access_token=<access_token>' 
  "https://graph.facebook.com/<API_VERSION>/fbe_business"

Response

{
  "page_cta": {
     "feature_instance_id": id1,
     "enabled": true,
     "cta_button_text": "Book Now",
     "cta_button_url": "https://partner-site.com/foo-business1",
     "below_button_text": "Powered by FBE Partner"
  },
  "page_ctas": [
    {
        "feature_instance_id": id1,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business1",
        "below_button_text": "Powered by FBE Partner"
    },
    {
        "feature_instance_id": id2,
        "enabled": true,
        "cta_button_text": "Book Now",
        "cta_button_url": "https://partner-site.com/foo-business2",
        "below_button_text": "Powered by FBE Partner"
    }
  ],
  “ig_cta”: {...}
  "ig_ctas": [{...}, {...}],
  “ads”: [
    {
      "feature_instance_id": id3,
      “enabled”: true,
    },
    {
      "feature_instance_id": id4,
      “enabled”: true,
    },
  ],
  ...
}

Testing

Prior to testing, send your Meta representative:

1. Features you want to enable.

2. User IDs of the individuals who will test the flow.

3. Your test app id so that we can allowlist that app for v3.

4. Give your Meta representative a role on your test app if you need help with testing.

To test these v3 changes, go through the onboarding flow and ensure:

1. You receive a webhook upon install and uninstall.

2. Webhook, Installation API, and Feature Configuration API have the updates mentioned above (accurately shows installed and uninstalled features).

3. The Feature menu reflects the features you want your businesses to install (by vertical).

You can test the onboarding flow by:

1. Going through Business Login.

2. Going through the Business Apps (if applicable)

Make sure to send the correct business configuration object for the features you want, and the UI you want to see in Business Login and Business Apps.

Feature List

MBE, v3 offers the following features that you can enable for your businesses. All of these features can be passed in via the FBE Installation API (during the installation flow), but as noted in the table, not all are configurable via the Feature Configuration API (after the merchant or advertiser has already installed MBE).

Sample Code for messenger_chat

<div class="fb-customerchat"
            page_id=PAGE_ID 
</div>

Verticals List

Identify which vertical(s) your app belongs to:

Intents (Use Cases) by Vertical

Ads

Creative

E-Commerce

Appointment

Reservations

Food and Drink

Lead Ads

Measurement and Optimization

Data Integration