# Meta Ads

## Overview

The Meta Ads connector allows you to integrate Meta’s advertising capabilities into Bird. With this connector, send segments to create Meta audiences,  sync leads from Meta, fetch ad campaigns, and send ad events directly from Bird.

#### Key Features

* **Sync Bird Segments to Meta as Custom Audiences**: Create, update, and sync custom audiences.
* **Sync Meta Leads as Bird Contacts**: Retrieve leads generated from ads.
* **Workflow Actions available in Flows:** 
  * Get Audience: Retrieve all audiences linked to the account.
  * Fetch Me: Retrieve information about the authenticated user.
  * Fetch Ad Accounts
  * Fetch Form Leads
  * Fetch Campaigns: Retrieve a list of ad campaigns.
  * Fetch Adsets: Retrieve adsets for a campaign.
  * Fetch Ads: Retrieve ads under an adset.
  * Fetch Leads: Retrieve leads generated by an ad.
  * Populate Info: Populate information about an ad campaign.
  * Send Ad Events: Notify Meta of other events via the Conversions API.
  * List Custom Audiences: List all custom audiences for the Ad Account.
  * Add to Custom Audience: Add contacts to a custom audience.
  * Remove from Custom Audience: Remove contacts from a custom audience.
  * Create Custom Audience: Create a new custom audience.

***

## Installation

To install the Meta Ads connector, follow these steps:

* **Navigate to Integrations**: Go to **Settings > Connectivity > Integrations** section within Bird.
* **Select Meta Ads**: Search and select "Meta Ads" from the Marketplace

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FkH1dGGK0W48CQmm3d8kU%2FScreenshot%202025-11-12%20at%204.15.01%E2%80%AFPM.png?alt=media&#x26;token=1fdc1758-225b-4335-9f02-25e77efda571" alt="" width="375"><figcaption></figcaption></figure>

* **Click Install**: Begin the installation process.

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FFJ5BU6sOY4wvh41WoWGm%2FScreenshot%202025-11-12%20at%204.15.10%E2%80%AFPM.png?alt=media&#x26;token=82b652ea-402f-44d6-ace3-6749aa6e3679" alt=""><figcaption></figcaption></figure>

* **Select a Use case:** You can select a use case whether you want to sync contacts vs send conversion events
* **Log in to Facebook**: Authenticate your Facebook account. Ensure you have admin permissions for your Facebook Marketing account.
* **Grant Permissions**: Approve the required permissions for Bird to access your Meta Ads account.
* **Complete Setup**: After authorising, the Meta Ads connector will be available for use in Bird workflows.

### Sync Bird Segment to Meta Custom Audience

Once the integration is installed, navigate to the **Config** tab.

* You will see the following data flow created: **Replace a Meta Ads Audience with a Bird Segment**
* Click on **View Data Flow**

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FKVNWI3WCauc8d1gyybJE%2FScreenshot%202025-11-12%20at%204.07.39%E2%80%AFPM.png?alt=media&#x26;token=fe0cae59-ca03-4a3d-8b83-40392f931c43" alt=""><figcaption></figcaption></figure>

* Navigate to the **Configuration** tab within the data flow

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FBtFMCmOwOVQyrGriq5C7%2FScreenshot%202025-11-12%20at%204.26.13%E2%80%AFPM.png?alt=media&#x26;token=0c6e4625-2f91-454d-ae79-dbe0ec6e6bce" alt=""><figcaption></figcaption></figure>

* Under **Source** section
  * Turn on **Fetch All on First Run** if you want to sync existing contacts in the segment as well and not the new contacts which would be added&#x20;
  * You can keep **Source Attributes** empty to allow the default configuration of attribute mapping
  * Select your Source Segment you want to sync and click on **Save Configuration**

<div><figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FmSohfnfBeJlPfLnrh2PM%2FScreenshot%202025-11-12%20at%204.30.20%E2%80%AFPM.png?alt=media&#x26;token=ffac3e00-4a04-4c20-babf-3533cba0c479" alt=""><figcaption></figcaption></figure> <figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FBaGo1IT9iM1SxYvICqQH%2FScreenshot%202025-11-12%20at%204.30.37%E2%80%AFPM.png?alt=media&#x26;token=29770317-5171-4249-a49f-58a11f51036e" alt=""><figcaption></figcaption></figure></div>

* Under **Destination** section
  * Select the **Meta Ad Account** to which you want to sync the custom audience
  * Select the **Meta Audience** to which you want to sync. You can also create a new one.
  * Click on **Save Configuration**

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FMiZeTp0zDwgNI7rwDMbJ%2FScreenshot%202025-11-12%20at%204.31.00%E2%80%AFPM.png?alt=media&#x26;token=f0942503-7eb2-4922-a61c-e3a0aabaeffa" alt="" width="375"><figcaption></figcaption></figure>

* Once done, turn the toggle ON to Enable the data flow to start the sync.

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2F9SCwEs2lQuhaNuT04Id7%2FScreenshot%202025-11-12%20at%204.37.49%E2%80%AFPM.png?alt=media&#x26;token=21a8ce18-ac8d-456e-bf8b-e639b7714616" alt=""><figcaption></figcaption></figure>

To sync more segments to Meta Audience, you can go to **Settings > AI & Automation > Data Flows**

* Clone the original data flow for **Replace Meta Ads with Bird Segment** from **3 dots > Clone**

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FUUT15NwbTVXAPwTv9hnY%2FScreenshot%202025-11-12%20at%204.40.07%E2%80%AFPM.png?alt=media&#x26;token=2617102b-641d-48f3-85d0-88ec75224c5a" alt=""><figcaption></figcaption></figure>

* Update the segment under **Source**
* Update the Meta Audience under **Destination**
* Click on **Save Configuration**
* **Enable** the data flow

### Sync Meta Leads to Bird Contacts

Once the integration is installed, navigate to the **Config** tab.

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FKVNWI3WCauc8d1gyybJE%2FScreenshot%202025-11-12%20at%204.07.39%E2%80%AFPM.png?alt=media&#x26;token=fe0cae59-ca03-4a3d-8b83-40392f931c43" alt=""><figcaption></figcaption></figure>

* You will see the following data flow created: **Sync Meta Ads Form Leads to Bird Workspace Contacts**
* Click on **View Data Flow**

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FG0Zo5qFMY3ezicAcSugh%2FScreenshot%202025-11-12%20at%204.42.18%E2%80%AFPM.png?alt=media&#x26;token=a1b6b6f7-9513-480b-bb12-1a1bd5d0f6a1" alt=""><figcaption></figcaption></figure>

* Navigate to the **Configuration** tab within the data flow

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FLlF4wlhEmxvRP9Xd1B1i%2FScreenshot%202025-11-12%20at%204.44.06%E2%80%AFPM.png?alt=media&#x26;token=2f431267-be04-4c0d-becf-51b9a6fa77f8" alt=""><figcaption></figcaption></figure>

* Under **Source** section
  * Enter the **Form ID** for the Meta Ads Lead Form
  * Click on Save **Configuration**
* Under **Destination** section
  * Select the list to which you want to sync the contacts into
  * You can Enable Automations if you want to trigger journeys based on Added to List or Contact Updated triggers&#x20;

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FpfieGytjmg3O5hTacmyS%2FScreenshot%202025-11-12%20at%204.47.26%E2%80%AFPM.png?alt=media&#x26;token=ccd8b188-baae-48d1-9da8-d51c406a374b" alt="" width="375"><figcaption></figcaption></figure>

* You can also select to subscribe contacts to different channels

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FUp7XGByr0lsZVCLSLHIw%2FScreenshot%202025-11-12%20at%204.47.46%E2%80%AFPM.png?alt=media&#x26;token=14f13ce5-3c77-4aef-b5b7-1d43abd9c5cb" alt="" width="375"><figcaption></figcaption></figure>

* Click on Save **Configuration**

Once done, turn the toggle ON to Enable the data flow to start the sync.

<figure><img src="https://3861485111-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FU9kiDiTGVD8kkbnKKyEn%2Fuploads%2FchAJ3Fex2k0LpYCQpLvI%2FScreenshot%202025-11-12%20at%204.49.18%E2%80%AFPM.png?alt=media&#x26;token=1cbf6da0-fd1d-4d02-bd96-24964bd2a0c8" alt=""><figcaption></figcaption></figure>

### Sending Ad Events

#### Overview

The "Send Ad Event" action allows you to notify Meta of messaging-related conversion events, such as leads or sales generated via WhatsApp, Messenger or Instagram. These events are sent using the Conversions API and can be configured within a Bird flow.

#### Supported Event Types

The Conversions API for business messaging events supports the following events:

* Purchase
* LeadSubmitted
* InitiateCheckout
* AddToCart
* ViewContent
* OrderCreated
* OrderShipped

Refer to [Meta’s Conversions API Business Messaging Documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/business-messaging) for detailed event parameter requirements.

#### Using the Send Ad event action

1. **Add the "Send Ad Event" Action**
   * Drag and drop the "Send Ad Event" step into your Bird flow.
2. **Enter the Dataset ID**
   * Input the dataset ID provided by Meta to identify the data source for the events.
3. **Select the Event Name**
   * Choose the appropriate event name from the dropdown (e.g., Lead, Message Sent, etc.).
4. **Set the Channel Slug**
   * Specify the channel where the event occurred (e.g., WhatsApp, Messenger, Instagram).
5. **Add User Data**
   * Include the necessary user data fields as an object.&#x20;
     * For Messenger add:
       * `page_id`: ID of the page where the event occurred.
       * `page_scoped_user_id`: User ID scoped to the page.
     * For WhatsApp add:
       * `whatsapp_business_account_id`: ID of the WhatsApp Business Account.
       * `ctwa_clid`: Click-to-WhatsApp tracking ID.
     * For Instagram add:
       * `instagram_business_account_id`: ID of the Instagram Business Account.
       * `ig_sid`: Instagram session ID.
6. **Add Custom Data (Optional)**
   * Provide additional event-specific data as key-value pairs, such as:
     * `currency`: Currency used for the transaction.
     * `value`: Transaction value.
7. **Save and Test**
   * Save the configuration and run a test to ensure the event is correctly sent to Meta.

#### Example Configuration

Here’s an example of how to configure the "Send Ad Event" action:

* **Dataset ID**: `12333`
* **Event Name**: `Purchase`
* **Channel Slug**: `WhatsApp`
* **User Data**:
  * `whatsapp_business_account_id`: `<WHATSAPP_BUSINESS_ACCOUNT_ID>`
  * `ctwa_clid`: `ARAkLka8rmFleiCkTEJQ-QTWrRiyYHAFDLMNDBH0CD3apjd0HR4irJ6LEkR7JwFF4XvnO2E4`
* **Custom Data**:
  * `currency`: `USD`
  * `value`: `123`

When executed, this data is securely sent to Meta, allowing for efficient tracking of messaging-related conversions.

For more information, visit [Meta’s Conversions API Documentation](https://developers.facebook.com/docs/marketing-api/conversions-api/business-messaging).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bird.com/applications/integrations/integrations/supported-integrations/meta-ads.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.