FBE Creative Onboarding

The Facebook Business Extension (FBE) allows your users to easily upload creative assets across the Meta family of apps by connecting with a new or existing Business Manager. Using the Business Manager returned after completing this flow, partners can upload creative assets to Facebook on behalf of their clients:

This document outlines the main prerequisites for the FBE Creative flow along with the steps required to complete the process. Please refer to the Facebook Business Extension guide for specific details on overall integrations.

Example — Onboarding flow from partner surface (Business Login)

Before You Start

1. Register as a Facebook developer to access our developer tools and create Facebook apps.

2. If you haven’t yet, create a Meta app.

3. Your Meta app must be owned by a Business Manager that is a verified business. Learn more about how to verify your business.

4. Create a test app and use it to perform all new development and testing. Be sure to assign a different Business Manager to your test app.

5. Private Permissions/Capability:

• manage_business_extension — Access to Facebook Business Extension. Once this capability is issued to your app, you can find the FBE Developer Panel under Products.

• Business_creative_asset_management — Access to creative related asset management apis. After granted with this capability, you can have access to the following permissions:

  • business_creative_insights: Access business creative asset insights.

  • business_creative_management: Allows your app to create, edit and share new folders and upload assets to these within the context of your own business entity.

  • business_creative_insights_share (in development): An optional permission used in the folder sharing flow. If granted by the user, your app will be able to share the creative folder to other businesses and allow them to view creative asset insights.

After App Review is Complete

Generate a partner access token:

• Generate an admin system user access token under your business manager by following these instructions.

• Ensure that this token has business_creative_insights, business_creative_management and business_management permissions selected in the 'available scopes' step.

Implement the ‘Send My Design to Facebook’ Button

This button is used to send an asset to the user’s Facebook Media Library from your app. During this process, your app will need to allow the user to select or create a folder to send the asset to.

We recommend two approaches to doing this:

1. (At minimum) The user only has the option to choose or create a top-level folder. Under the selected business context, query all the top-level folders the user has access to. Ask the user to either choose an existing top-level folder or create a new one. Users can either specify the folder name or use the default folder name <YourBusinessName>_<UserBusinessName>_<UserName>. Upload assets to the selected or new top-level folder. This approach requires minimal UI work and API details can be found in Step 3 below.

2. (Optional) The user has full folder and subfolder navigation control. Under the selected business context, query all the top-level folders the user has access to and ask the user to either choose an existing top-level folder or create a new one. For a new folder, either ask the user to name the folder or use the default name <YourBusinessName>_<UserBusinessName>_<UserName>. Under the selected top-level folder, the user has the option to navigate to an existing subfolder, create a new subfolder, or upload assets. With this option, you will need to implement folder navigation in your UI. API integration instructions can be found in Step 3 and Step 4 below.

The specific steps required to implement this flow are as follows:

1. Implement Facebook Business Extension
2. Get business context
3. Select or create a top-level folder
4. Select or create a subfolder
5. Upload images/videos
6. Request folder sharing to you (optional)
7. View images/videos insights (optional)

1. Implement Facebook Business Extension

When the user sends a creative asset to Facebook for the first time, you need to prompt the Facebook Business Extension to ask the user to authenticate and grant your app necessary permissions and access to assets, in the form of access tokens, to access their data on Facebook. See Facebook Business Extension: Get Started to implement Facebook Business Extension into your app. Follow the Business Apps guide to enable your app to surface on Business Apps.

To prompt the Creative flow:

• Pass in channel: CREATIVE and business_vertical: CREATIVE under setup.
• Use business_creative_management and business_creative_insights permissions

  • Required to query business IDs, create folders and upload creative assets to the folder
• (Optional) Use business_creative_insights_share permission

  • Allows the user to share with you the folder with permission for the VIEW_INSIGHTS task

Using the user access token returned from this prompt, you can make API calls on the user’s behalf.

Required Configurations

Extras

Setup

Use this object to define the settings for the end user's Facebook presence

Business Config

Use this object to configure the business settings for an end user. This includes CTAs, Services card, and more. Each field includes a "type" linked to the respective tables below.

FBEBusinessPropertiesConfigData

Use this object to configure the businesses name.

2. Get Business Context

After the user finishes the FBE onboarding flow above, you will receive the user’s Business Manager ID and access token either from the FBE Installation API or Webhook notification.

3. Select or Create a Top-Level Folder

Users can upload assets to the top-level folder or create sub-folders under the top-level folder.

First, check which top-level folders the user has permission to for the CREATE_CONTENT task, by making a request to the <business_id>/creative_folders endpoint (under development).

Get Top-Level Folder from the User’s Business

Request

curl -X GET \
    -F 'access_token={user-access-token}' \
https://graph.facebook.com/<API_VERSION>/<user_business_id>/creative_folders?filtering=[{field:"permitted_tasks", operator: "EQUAL", value:"create_content"}]

Response

{
 "id": "<folder_id>"
}

Ask the user to choose an existing top-level folder or create a new top-level folder within the context of the user’s Business Manager. For a new top-level folder, you can either ask the user to name the folder, or use <YourBusinessName>_<UserBusinessName>_<UserName> by default. If the user shares the folder back to you, it will be visible to both your business and the user’s business in the Facebook asset library.

Get User’s Business Info Request

Request

curl -X GET \
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>

Response

{
 "id": {business-id}
 "name": {user-business-name}
}

Create Top-Level Folder Request

Request

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Response

{
 "id": {top-level-folder-id}
}

4. Select or Create a Sub-Folder

If you want to support the full folder navigation flow, ask the user to choose an existing subfolder or create a new one under the top-level folder with the following requests:

Get Subfolder

• Requires business_creative_management permission

Request

curl -X GET \
    -F 'access_token={user-access-token}' \
    https://graph.facebook.com/<API_VERSION>/<parent_folder_id>/subfolders?fields=name

Response

{
 "data": [
   {
     "name": "<subfolder_name>",
     "id": "<subfolder_id>"
   }
 ]
}

Create Subfolder

• Requires business_creative_management permission

Request

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F "parent_folder_id={parent-folder-id}"
    -F 'access_token={user-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Response

{
    "id": {sub-folder-id}
}

The folder and subfolder can be deleted by sending a DELETE request to the <folder_id> or <subfolder_id> endpoint.

5. Upload Images and Videos to Subfolder

Upload user’s creative assets to the subfolder.

• Requires business_creative_management permission

Upload Images

Request

curl -X POST \
    -F 'bytes={image-content-in-bytes-format}' \
    -F 'name={image-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    https://graph.facebook.com/{version}/{business-id}/images

Response

{
    "images":{
         "{image-name}":{
             "id":"{business-creative-image-id}",
             "hash":"{hash}",
             "url":"{image-url}"
         }
    }
}

Upload Videos

Upload a video in a single request if it is less than a few megabytes, or upload it in chunks (see the next section below). Make your API call for video upload at graph-video.facebook.com instead of graph.facebook.com.

Example — Send a POST to {business-id}/video and include the name of your video, the source, and the subfolder ID.

Request

curl -X POST \
    -F 'name={video-name}' \
    -F 'source='@{video-path}'' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    https://graph-video.facebook.com/{version}/{business-id}/videos

Response

{
  "success": true,
  "business_video_id": "<business_video_id>"
}

Upload Chunked Videos

For larger videos, send one start request, one or multiple transfer requests, and one finish request.

To make a start request and create a video upload session, send a POST request to /{business-id}/videos, set upload_phase field to start, and specify file_size, in bytes

Request

curl -X POST \
 -F 'title={video-name}' \
 -F 'creative_folder_id={subfolder-id}' \
 -F 'access_token={user-access-token}' \
 -F 'upload_phase=start' \
 -F 'file_size={video_file_size_in_bytes}' \
 https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Response

{
    "upload_session_id": "{session-id}",
    "video_id": "{video-id}",
    "start_offset": "0",
    "end_offset": "52428800"
}

To upload [0, 52428800] from your video, slice the file into chunks according to the start and end offsets, then send those chunks with transfer requests. We send you new offsets for each chunk -- use these new offsets to upload each chunk.

Example: Send your first chunk

Request

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    -F 'upload_phase=transfer' \
    -F 'upload_session_id={session-id}' \
    -F 'start_offset=0' \
    -F 'video_file_chunk=@{binary-chunk-filename}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Response

On success, we respond with the offsets for your next chunk

{
  "start_offset": "52428800", //Start byte position of the next file chunk
  "end_offset": "104857601" //End byte position of the next file chunk
}

Cut and upload the second chunk with the range [52428800, 104857601] from your file and send it:

Request

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={subfolder-id}' \
    -F 'upload_phase=transfer' \
    -F 'start_offset=52428801' \
    -F 'upload_session_id={your-upload-sesson-id}' \
    -F 'video_file_chunk={binary-chunk-filename}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Response

Send all additional chunks until start_offset equals end_offset:

{
 "start_offset": "152043520",
 "end_offset": "152043520"
}

The above response means you uploaded the whole file. Now you need to post this video and close the upload session.

Request

curl -X POST \
    -F 'title={video-name}' \
    -F 'access_token={user-access-token}' \
    -F 'creative_folder_id={business-creative-folder-id}' \
    -F 'upload_phase=finish' \
    -F 'upload_session_id={session-id}' \
    https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

If you get errors during an upload, you can retry uploading that chunk. Typically errors are due to response issues. Retry your upload for the chunk that failed. For more information about errors, see:

• Resumable Upload Errors
• Using Graph API, Handling Errors

Your app should inform the user that the upload has succeeded, and present a deep link to this creative behind a ‘View creative in my Facebook asset library’ call to action. The deep link of the folder or asset is:

https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id} (under development)

This link directs the user to the business selection page if the user has multiple Business Managers. To remove business ambiguity, you can provide business context in the url as follows:

https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}&business_id={client_business_id}

The deep link url can also be obtained by making a GET request on endpoint:

curl -X GET \
    /<folder_id or asset_id>
        ?fields=['media_library_url']
        &access_token=<user_access_token>

The link allows the user to go to the folder or asset directly under Facebook asset library.

6. Request Folder Sharing to You (Optional)

You may request the top-level folder to be shared with you if you want to manage the folder or view insights for the assets. Send a POST request to: {business-creative-folder-id}/agencies and assign permitted_tasks to CREATE_CONTENT.

Share Folder

• Requires business_creative_management permission

Request

curl -X POST \
    -F 'permitted_tasks=['CREATE_CONTENT','VIEW_INSIGHTS']' \
    -F 'business={partner-business-id} ' \
    -F 'access_token={user-access-token}' https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies

The response is in one of two types depending on the user's role in their business organization:

1) If the client token represents a business admin:

The API will establish a partnership agreement between user business and client business.

Response

If there is an established partnership agreement between the user business and your business (user business shared a folder with you, and you accepted a sharing request before):

{ 
    "success": true
}

If you did not accept any sharing request from the user business yet:

{
    "success": true,
    "share_status": "In Progress"
}

In this scenario, your business will need to accept the sharing request before your business is able to access all capabilities that are enabled by the share (view, create, and so on).

To list all partnership agreements that are pending approval, send a request to {business-id}/received_sharing_agreements using your partner access token and set request_status to IN_PROGRESS. You need business_creative_management and business_management permission for this action.

List All Partnership Agreements

Request

curl -i -X GET https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/received_sharing_agreements
    ?request_status=IN_PROGRESS
    &access_token={partner-access-token}"

You can accept a sharing request by sending a POST to business_sharing_agreement_request_id and set request_status to APPROVE. You only need to do this the first time someone shares a folder with your business. You need business_management permission for this action:

Accept Partnership Agreements

Request

curl -X POST \
    -F 'request_status=APPROVE' \
    -F 'access_token={partner-access-token}' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>

Response

{ 
    "success": true
}

Alternatively, you can approve pending sharing requests in the Business Manager UI. To see pending requests in Business Manager, go to Settings > Requests > Received Requests, where you can see more information about the request.

2) If the client token represents a business employee:

The API triggers a Notification workflow to send an email notification to business admins to approve the request.

Response

{
   "success": true,
   "share_status": "Pending"
}

In response to this state, your app should inform the user that:

• a request has been initiated to their business admin via email to approve sharing request
• another email has been sent to the user about the request

To list all pending agreements that have been initiated in the user’s business, send a request to {business-id}/attempted_sharing_agreements and set request_status to IN_PROGRESS, set requesting_business_id to the user's Business Manager ID. You need business_creative_management and business_management permission for this action.

List All Pending Folder Sharing Agreements

Request

curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/attempted_sharing_agreements
    ?request_status=IN_PROGRESS
    &requesting_business_id=<user_business_id>
    &access_token={partner-access-token}

List All Pending Folder Sharing Agreements With Request ID

Alternatively, if you have the request ID, you can directly get status by sending a request to {request_id}.

• Requires business_creative_management permission

Request

curl -i -X GET  \
    https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>?fields=status

When a business admin approves the request, the status changes to APPROVE and the folder is shared back to your Business Manager if the user’s business and your business have established a sharing agreement relationship (user business shared a folder with you, and you accepted a sharing request before). Otherwise, the share_status is updated to IN_PROGRESS. You can list all partnership agreements with IN_PROGRESS status and accept them via API or in the Business Manager UI.

7. View Images/Videos Insights (Optional)

When the user shares a folder to you with permission for the VIEW_INSIGHTS task, you can read insights of business images and videos under the shared folder by making a GET request on <business_asset_id>/insights endpoint.

Business Creative Insights

• Requires business_creative_management and business_creative_insights permission.

Request

curl -i -X GET  \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ASSET_ID>/insights
    ?breakdowns=["age","gender"]
    &fields=impressions,inline_link_clicks,age,gender,date_start,
    &time_range={"since":"2019-08-01","until":"2019-08-22"}
    &access_token={partner-access-token}"

Response

{
 "data": [
   {
     "impressions": 99,
     "inline_link_clicks": 1,
     "age": "18-24",
     "gender": "female",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
   {
     "impressions": 198,
     "inline_link_clicks": 2,
     "age": "18-24",
     "gender": "male",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
   {
     "impressions": 464,
     "inline_link_clicks": 2,
     "age": "25-34",
     "gender": "female",
     "date_start": "2019-08-01",
     "date_end": "2019-08-22"    },
 ]
}

The breakdown can be by:

• gender
• age
• country
• publisher_platform
• platform_position
• device_platform
• ad_id
• objective
• optimization_goal
• time_range (requires a date in the format of "YYYY-MM-DD", which means from the beginning midnight of that day.)

Managing Shared Folder Using Partner Token Directly

For managed service partners, you can manage the top-level folder with a partner access token if the folder has been shared back to you with proper permitted tasks which grant you:

• CREATE_CONTENT task permission on the folder, which allows your app to create subfolders and upload images and videos to the folder.
• (Optional for users) VIEW_INSIGHTS task permission, which your app can use to view performance insights of any creative assets stored in this folder.

1. Check Parent Folder Permission

Call <business_id>/creative_folders endpoint to get all parent folders that are shared to you under the user’s business.

• Requires business_creative_management permission

Get folders from the user's business

Request

curl -X GET \
     -F 'access_token={partner-access-token}' \  https://graph.facebook.com/<API_VERSION>/<partner_business_id>/creative_folders?filtering=[{field:"owner_business_id", operator:"EQUAL", value:"user_business_id"}]

Response

{ 
    "data": [
       { 
            "id": "<shared_folder_id>" 
       }
    ]
}

Get permitted tasks you have on the folder

Request

curl -X GET \
 -F 'access_token={partner-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<folder_id>/agencies

Response

{
 "data": [
   {
     "id": "<partner_business_id>",
     "name": "<partner business name>",
     "permitted_tasks": [
       "VIEW_INSIGHTS",
       "VIEW_CONTENT",
       "CREATE_CONTENT",
       "MANAGE_CONTENT",
       "MANAGE_PERMISSIONS"]
   }
 ],
}

• CREATE_CONTENT task permission task is required to upload images and videos to a shared folder
• VIEW_INSIGHTS task permission task is required to query creative insights of images or videos under a shared folder

2. Create Subfolder under Parent Folder

With CREATE_CONTENT task permission on the parent folder, you can create a subfolder in a shared folder.

• Requires business_creative_management permission

Create subfolder

Request

curl -X POST \
    -F "name={folder_name}"
    -F "description={description}"
    -F "parent_folder_id={parent-folder-id}"
    -F 'access_token={partner-access-token}' \
 https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Response

{
 "id": {subfolder-id}
}

3. Upload Images and Videos to Subfolder

Follow the same steps listed in Step 5. Upload images and videos to subfolder with partner token.

Tracking the Image/Video Facebook Asset ID

When your app uploads an image or video to Facebook’s asset library, Facebook’s API will return an ID for that asset.

To facilitate ongoing continuity, your app will need to track the asset’s ID against the project/workspace that produced this image/video in your app.

This will allow for streamlined ‘edit’ and ‘update’ use cases, which will be supported in the future, for example:

• A user in your app who decides to continue editing an asset after it has been published to Facebook and used in an ad. The user will be prompted with streamlined ‘update’ or ‘run a split test’ flows if your app sends the original asset ID when uploading an updated version of the image/video.
• A user in the Facebook Ad Insights panel has the ability to ‘edit’ their creative, including editing the image/video which will send the user to your app, passing in the asset ID. In response to this, your app will be able to open the project that created this asset, allowing the user to pick up where they left off.

Provide Deep Link URL to Asset and Create Ad and Post Actions

Deep Link URL for Asset

• Query the uploaded image/video asset's media_library_url field

Request

curl -X GET \
    -F 'access_token={partner-access-token}' \
https://graph.facebook.com/<API_VERSION>/<asset_id>?fields=media_library_url

Deep Link URL for Creating an Ad or a Page Post

• Append &action=CREATE_AD or &action=CREATE_POST at the end of the deep link of above step.

Example:

https://business.facebook.com/asset_library/business_creatives/?object_id=2838437832929622&action=CREATE_AD

Next Steps

• Get Webhook notifications about businesses installing and uninstalling FBE.
• Fire pixel events for every FBE-integrated business on your platform.
• Add entry point to our Feature Management View from your surface.
• Allow businesses to uninstall FBE.
• Submit for FBE Integration Review. Once your integration is approved, you will be able to launch your application to public users.