Get Asset IDs and Access Token

After the user installs the Facebook Business Extension, and you have their user access token (which is used to make API calls for the user), you need to get the pixel ID, Instagram Business ID, Page ID, Business Manager ID, Ad Account ID, Catalog ID (optional) or access token from the user to configure the relevant features. These IDs will be used for API endpoints and business configurations.

With the OBO solution, the client can get the access token, using the partner Business Manager's admin system user's access token as well, instead of only the client Business Manager's admin's access token.

Gather IDs for API Endpoints and Business Configurations

Here's how you get that information:

• Webhook—Required for all platform partners that want to be listed in the App Store
• FBE Installs API endpoint—Recommended for self-hosted businesses

System User Creation

After a user installs FBE, the extension generates an employee system user on the client's Business Manager. Naming for this new system user follows the schema {App Name} System User (FBE).

System users represent servers or software that make API calls to assets owned or managed by a Business Manager.

This system user has permissions to all associated FBE assets with the following task permissions:

1. Page: 'MANAGE'
2. Ad Account: 'MANAGE'
3. Catalog: 'MANAGE'
4. Pixel: 'EDIT'

Get System User Token via API

If you receive a user access token through a Webhook or the Business Login after a FBE install, you can use that same token to get the Business Manager's system user access token. To do that, make the following API call:

curl -X POST \
  -F 'app_id={app_id}' \
  -F 'scope={permissions}' \ 
  -F 'access_token={access_token}' \
  -F 'fbe_external_business_id={fbe_external_business_id}' \
  https://graph.facebook.com/<API_VERSION>/<client_business_manager_id>/access_token

For the scope field, use the manage_business_extension permission, but depending of your use case, also ads_management or catalog_management might be needed.

For the access_token field, you can pass a user access token (user_access_token) or a Partner Business Manager's Admin System User Access Token (partner_bm_admin_system_user_token). Learn more about Business Access Token.

Webhook

To receive prompt updates about installations, uninstallations, and reconfigurations of FBE, we fire Webhook events each time one of your businesses installs, modifies, or uninstalls FBE.

Each time a user installs or modifies FBE, your app should inspect the Webhook configuration to understand what assets the user has modified, added, or removed from their connection with your app. Your app's behavior should update based on the most current connected assets.

Setup Requirements

1. Create an endpoint on a secure server that can process requests from Facebook: Verification Requests (GET) and Event Notifications (POST).
2. Configure the FBE webhooks subscription in the App Dashboard:
   • In the Facebook Business Extension section of the App Dashboard, go to the Setup tab, scroll down to the Webhooks card, then click Edit Callback URL.
   • Enter your endpoint's URL in the Callback URL field and enter a string in the Verify Token field. We will include this string in all Verification Requests.
   • Once you click Verify and Save, we'll send your endpoint a verification request which you must validate.
   • The fbe_install webhook will be automatically subscribed. The card also features a toggle switch which can be used to deactivate the subscription if the need arises.

Parsing Webhook events

Each time an install webhook is received, your app needs to perform the following actions.

For new installations

1. Store the access token and token type, and record the assets that your app has been granted access to.
2. Enable the set of features based on which assets have been granted.
3. If an asset required for a specific feature is missing, disable only that feature. For example, if your app has been granted access to a catalog, but not a pixel, only implement the catalog-powered feature, not the pixel-powered feature.
4. Inform the user with an update on how your app is behaving based on which assets they have access to.

For existing installations

1. Update the access token, token type, and your record of assets that your app has been granted access to.
2. Update the set of features your app will implement for this business based on which assets have been granted.
3. Inform the user with an update on how your app is behaving based on which assets they have access to.

Parsing Webhook at uninstall

Perform the following steps at uninstall:

1. Disable features that your app implements for this business.
2. Inform the business about the change to their configuration.

What's Included with Webhook Payload

Response Fields

Example — Payload with boolean onsite_commerce_eligible field

{
  "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
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

FBE Installation API

For any business that has installed FBE, you can query for basic installation information (pixel_id and a list of profiles with an IG Business ID and/or Page ID) using the following endpoint:

Example

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": [{
    "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
                        },
                        {
                        "shop_status": array
                        },
                        {
                        "shop_status_info": array
                        }
                }
         ]
    }]
}

The response includes the following fields. These are now the source of truth in connected assets od “installed_features” list:

Feature Configuration API Response

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

For non-customizable features, 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,
    },
  ],
  ...
}

Next Steps

• Configure Business Features
• Fire Pixel Events
• Update Your Catalog