In the hybrid approach, you run the ads using your own Facebook ad accounts and pages while allowing customers to connect their Facebook and Instagram pages. This allows customers to select an Instagram post (or other IG content) they’ve previously uploaded, while still leveraging your ad management infrastructure.

Tradeoffs:

• Pros:
  • Ads are run directly from your ad account and Facebook pages, ensuring consistency in campaign management.
  • Customers can use their own Instagram content in the campaign.
• Cons:
  • You must ensure that customers have a valid Facebook page and Instagram page connected.
  • There is additional overhead to validate that their connected pages and ad account statuses are in good standing before launching a campaign.

0. Dev Environment Setup

When using an integration that allows login with Facebook - you will need to run on https:// given Facebook’s restrictions.

Accordingly, if running your setup on localhost:3000, please enable HTTPS for localhost. Otherwise, the FB login won’t show up.

1. API Authentication

All API requests must include the x-api-key header, which corresponds to the brand configured during onboarding.

📘

If your integration involves multiple users, each user will have their own brand associated with your partner account. In this case, you must also include the x-brand-id header in every request to specify which user's brand is being accessed.

For all advertising-related flows, it is essential to identify the brand being used, whether it is the default brand or one explicitly specified via the header. The brand must be connected to a Facebook account with permissions for the ad account and the pages used in the campaigns.

2. Connection Flow

2.1 Connecting Your Account to Facebook

Allowing your customers to login with Facebook and use their pages + ad accounts:

Using a Script for User Login:

This method allows you and your users to log in to their respective Facebook accounts through an integration script.

2.1.1 Allow your customers to login with FB + pull their pages to show associated Instagram posts:

Using a Script for User Login:

If you choose to use the connection script, you need to import the following script into your site:

<script src="https://docs.partner.symphonyos.co/symphony-connect.min.js" async></script>

Then, create a clickable element (e.g., a button) with the id set to sym-facebook-button and the attributes data-api-key, data-user-id, and data-environment.

📘

The data-user-id attribute represents the brand ID of the user attempting to connect. Sending this field empty indicates that the account connection is hybrid.

<button
  class="login-btn"
  id="sym-facebook-button"
  data-api-key="YOUR_API_KEY"
  data-user-id="YOUR_OPTIONAL_USER_BRAND_ID"
  data-environment="localhost"
>
  Log in with Facebook
</button>

When the button is clicked, a Facebook connection modal will appear. Upon completing the login process, the connection details will be stored for the brand.

Additionally, a custom login-success event will be triggered on the button, providing the user's connection details.

const facebookConnect = document.getElementById("sym-facebook-button");
const userCard = document.getElementById("userCard");

// Listen for the 'login-success' event
facebookConnect.addEventListener("login-success", (event) => {
  console.log("User logged in:", event.detail.user);

  // Display user information
  userCard.style.display = 'block';
  userCard.querySelector("img").src = event.detail.user.picture.data.url;
  userCard.querySelector("h3").textContent = event.detail.user.name;
});

You can find a complete example here for inspection or download.

2.2 Connecting Pages

2.2.1 Retrieve Pages

The fb_user_id field is the value of the id that is retrieved once the login is successfully completed.

curl -X 'GET' \
  '{{ADVERTISING_API}}/v1/meta/:fb_user_id/pages' \
  -H 'accept: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \

These endpoints, documented in the Meta Connect section of the Swagger documentation, return lists of pages associated with the connected Facebook account. Select the desired ad account and page, and retrieve their IDs.

2.2.2 Pulling Instagram Posts from a selected page

The request to create a campaign requires a media field, which can be either an instagram_post_id or public_video_links or public_image_links.

curl -X 'GET' \
  '{{ADVERTISING_API}}/v1/meta/hybrid/:fb_user_id/:fb_page_id/posts' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \

The response will return a set of IG posts - as long as the FB Page has a connected Instagram account.

{
        "id": "string",
        "ig_id": "string",
        "permalink": "string",
        "caption": "string",
        "media_product_type": "string",
        "media_type": "string",
        "media_url": "string",
        "is_shared_to_feed": true,
        "like_count": 0,
        "comments_count": 0,
        "thumbnail_url": "string",
        "timestamp": "2025-01-25T21:41:30.107Z",
        "username": "string"
}

When creating a campaign, you should then use the “media_url” passed here, in the public_video_links or public_image_links field, which is an array that can contain up to three videos or images. The thumbnail field is optional, and format_type specifies the type of content or the manner in which the video will be displayed, such as a reel, story, or feed.

2.2.3 Retrieve all hybrid connections

To get all hybrid connections, use the following endpoint:

curl -X 'GET' \
  '{{ADVERTISING_API}}/v1/meta/hybrid/connected' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {{YOUR_API_KEY}}' \

3. Flows

A simple workflow for using the API includes the following steps:

1. List Existing Campaigns: Retrieve a list of campaigns that have been created. 3.1 Retrieving the List of Campaigns

2. View Campaign Details:3.2 Get Campaign Details

   For each campaign, you can access its details, including:

   • General campaign information.
   • Analytics generated during its execution.

3. Create and Configure New Campaigns: Use the API to create and set up new campaigns tailored to your requirements. 3.3 Create Campaigns

4. Update Ongoing Campaigns: Explore the available workflows for updating a campaign currently in progress. Campaigns Management

4) Response and Webhooks

WEBHOOKS Documentation