Get Asset IDs and Access Token

Facebook Business Extension (v2) is currently only available to approved partners. If you are interested in becoming a partner, please contact your Facebook representative for access. FBE requires the manage_business_extension capability.

If you do not have a representative, please fill out this form if you are an eCommerce partner or this form (available on desktop only) if you are in the Services vertical.

After the user installs the Facebook Business Extension, v2, 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 can get that information:

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=ads_management,catalog_management,manage_business_extension' \ 
  -F 'access_token={user_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 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_use_token). Learn more about Business Access Token.

If the user is installing FBE via Instagram, the Webhook will return the system user's token that was generated on the client Business Manager, so you don't need to call this API.

Webhook

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

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 Webhooks product in your app's App Dashboard to subscribe to the User object's fbe_install field:
    • In the App Dashboard, go to Products > Webhooks, select User from the drop-down menu, then click Subscribe to this object.
    • 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.
    • Set the Include Values toggle to Yes.
    • Once you click Verify and Save, we'll send your endpoint a Verification Request which you must validate. If your endpoint successfully validates the request, you should see all fields you can subscribe to.
    • Subscribe to the fbe_install field.
    • Once configured, you can test it by sending a fbe_install sample notification to your server. Click the Test button and then Send to My Server.

These steps are explained in detail at Webhooks, Getting Started.

What's included with Webhooks?

  • External Business ID (business_id)—Unique identifier that you define for a business.
  • Business Manager ID (business_manager_id)—The business manager ID used for FBE.
  • Pixel ID (pixel_id)—Unique pixel ID for this business which you should store and use to fire pixel events.
  • Access Token (access_token)—User-level access token you should store and use to call the Catalog, Installation, and Feature Configuration APIs.

If the user is installing FBE via Instagram, the Webhook will return the system user's token that was generated on the client Business Manager.

  • Profiles (profiles)—List of profiles (a Facebook Page ID and/or an Instagram Business Profile ID). Use these IDs to create separate Graph API requests for other Facebook integrations you may have.
  • Pages (pages)—List of Facebook Page IDs. Use these IDs to create separate Graph API requests for other Facebook Page integrations you may have.
  • Instagram Profiles (instagram_profiles)—List of Instagram Business Profile IDs. Use these IDs to create separate Graph API requests for other Facebook/Instagram integrations you may have.
  • Ad Account ID (ad_account_id)—The ad account ID selected by user inside FBE. This ad account can be used to manage ads if your app has ads_management permissions.
  • Catalog ID (catalog_id)—The catalog ID selected by user inside FBE. This ID can be used to manage their product catalog.
  • Commerce - (onsite_eligible)— Indicates whether the selected assets are eligible for onsite commerce. The merchant must still have intent for onsite and select returns/shipping/payments on the partner site. See example below.

If profiles, pages and instagram_profiles fields are not included in the Webhook payload, this means the business has uninstalled FBE. In this case also the field access_token will not be included.

When you receive a Webhook event for a new installation, you must: 1) maintain a mapping of business_id to its pixel_id since pixel ID is unique for that business and you should use to fire standard pixel events and 2) update the inventory for that business using one of the Catalog PUSH APIs, if enabled.

Example — Payload with boolean onsite_eligible field

{
  "object":"user",
  "entry":[
    {
      "id":"<app_scoped_user_id>",
      "uid":"<user_id>",
      "time":<epoch_time>,
      "changes":[
      {
        "field":"fbe_install",
        "value":{
          "business_id":"<business_id>",
          "business_manager_id": "<business_manager_id>",
          "profiles":[
            "<page_id>",
            "<instagram_profile_id>"
          ],
          "pages": [
            "<page_id>"
          ],
          "instagram_profiles": [
            "<instagram_profile_id>"
          ],
          "commerce" {
            "onsite_eligible": bool,
          }
          "install_time":<install_time>,
          "pixel_id":"<pixel_id>",
          "access_token":"<user_access_token>" 
        }
      }
     ] 
    }
  ]
}

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": [
      {
         "pixel_id": "<pixel_id>",
         "profiles": [
            "<page_id>",
            "<instagram_profile_id>",
         ],
         "pages": [
            "<page_id>",
         ],
         "instagram_profiles": [
            "<instagram_profile_id>",
         ],
         "business_manager_id": "<business_manager_id>",
         "ad_account_id": "<ad_account_id>", 
         "catalog_id": "<catalog_id>",
         "commerce_merchant_settings_id": "<commerce_merchant_settings_id>",
         "onsite_eligible": "<onsite_eligible>"
      }
   ]
}

Similar to the Webhook above, the response includes the following fields:

  • Pixel ID (pixel_id)—Unique pixel ID for this business that you should store and fire events with
  • Profiles (profiles)—List of profiles (a Facebook Page ID and/or an Instagram Business Profile ID). These IDs can be used to make separate Graph API requests for other Facebook integrations. If profiles is empty, this means the business has uninstalled FBE.
  • Business Manager ID (business_manager_id)— Unique Business Manager ID selected by user inside FBE that you can use for converting access token into on behalf of system user access token.
  • Ad Account ID (ad_account_id)— The ad account ID selected by user inside FBE. This ad account can be used to manage ads if your app has ads_management permissions
  • Catalog ID (catalog_id)— The catalog ID selected by user inside FBE. This ID can be used to manage their product catalog.
  • Pages (pages)— List of Facebook Page IDs. Use these IDs to create separate Graph API requests for other Facebook Page integrations you may have. If the pages field is not included, this means the business has not connected any Facebook Pages with FBE.
  • Instagram Profiles (instagram_profiles)— List of Instagram Business Profile IDs. Use these IDs to create separate Graph API requests for other Facebook/Instagram integrations you may have. If the instagram_profiles field is not included, this means Instagram-related scope (for example, instagram_basic) is not included in the access token and/or the business has not connected any Instagram Business Profile with FBE.
  • Commerce Merchant Settings ID (commerce_merchant_settings_id)— Used to enable partners to read information regarding the selected FBE's Commerce Merchant Settings.
  • Commerce (onsite_eligible)— Indicates whether the selected assets are eligible for onsite commerce. The merchant must still have intent for onsite and select returns/shipping/payments on the partner site.