> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.funnelflux.pro/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Direct integration setup with Meta

This guide walks through our native Meta integration from start to finish: connecting your Meta login, linking an ad account to a traffic source, sending events to the Conversions API (CAPI), and pulling in costs and campaign names.

If you're unsure about any of the settings below, use our **Meta** traffic source template when you create the traffic source. Everything will be configured correctly.

If you haven't yet, read [Using traffic source integrations](https://help.funnelflux.pro/en/article/using-traffic-source-integrations-s4p02b/) first -- it explains how connections, traffic source links and event mapping fit together across all platforms. This article is the Meta-specific version of that flow.

Note that the older manual method -- pasting a Meta access token into a custom scenario -- still works and is described in [Using the Facebook Conversions API (CAPI) to track conversions](https://help.funnelflux.pro/en/article/using-the-facebook-conversions-api-capi-to-track-conversions-m9s4sp/). For new setups we recommend the native integration, as it gives you cost sync, name sync and Integration Logs, which custom scenarios don't.

## Step 1: Connect your Meta account

Go to Settings > Integrations > Traffic Sources and click **Connect** on the **Meta** card (it says **Add account** if you already have a Meta connection).

You'll be sent to Meta to log in and approve access. When you come back, the login shows up under **Connections** with an **Active** status:

![Traffic Source Integrations settings with an active Meta connection](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/01-meta-connection_la7z6n.png)

The Meta login must have access to the ad accounts and datasets/pixels you want to use -- we can only see what that Facebook user can see in Business Manager.

Meta access tokens are long-lived (around 60 days) and we refresh them before they expire. If a connection ever shows **Expired** or **Auth error**, click **Reauth** and log in again.

## Step 2: Link the traffic source to your ad account

Open your Meta traffic source (Assets > Traffic Sources > edit) and go to the **Integrations** tab.

In **Platform Integration**, fill in the fields in order -- each one appears once the previous one is set:

- **Traffic Source Integration Type** -- Meta.
- **Connection** -- the Meta login from step 1.
- **Ad Account** -- the ad account this traffic source spends from.
- **Dataset / Pixel ID** -- where your events should go in Meta Events Manager.

The chips in the top right (**Platform** > **Connection** > **Ad account** > **Dataset / Pixel ID**) turn green as you complete each step.

![Platform Integration for Meta: Dataset / Pixel ID picker and Meta Test Event Code](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/02-meta-platform-integration_1oyakwd.png)

### Picking the Dataset / Pixel `[1]`

We load the pixels your Meta connection can access, so in most cases you just pick yours from the list.

If it isn't listed -- for example the pixel is owned by a different business and shared in a way the API doesn't expose -- click **Enter ID manually** and paste the dataset or pixel ID from Events Manager. Click **Select from account pixels** to go back to the list.

If we can't load the pixel list at all, you'll see a warning and can still enter the ID manually.

Meta has been renaming pixels to "datasets", but for our purposes the ID is the same thing.

### Test event code `[2]`

While you're checking the setup, paste the test code from Meta Events Manager > Test Events into **Meta Test Event Code**. Events we send will then show up in Meta's Test Events tab, so you can see them arrive in real time.

**Remember to clear this field once you're done testing.** Events sent with a test code are meant for Meta's Test Events tool, not for your live campaigns.

**View delivery logs** under this section opens Integration Logs filtered to this traffic source.

Meta conversions are sent straight away -- there's no delay like with Google Ads or Microsoft Ads.

## Step 3: Check your tracking fields

Meta matches a server event to an ad click mostly via the click ID, `fbclid`, which Meta appends to your ad's URL automatically.

On a Meta traffic source this is the **External Click ID** tracking field, with the URL parameter `fbclid`. Go to the **Tracking Fields** tab and check it's there:

![Tracking Fields tab with External Click ID capturing fbclid](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/04-meta-tracking-fields-fbclid_1sihvvz.png)

We use the value in the External Click ID field plus the visitor's entry time to build Meta's `fbc` parameter. If the field is empty, missing or captures something else, Meta gets no click ID and matching gets much worse.

Along with it, for each event we send:

- the visitor's IP address and user agent
- a hashed external ID based on the visitor ID
- the page URL as the event source URL
- the `_fbp` browser cookie, when we have it
- hashed email, phone or zip code, if you pass them to us
- the value and currency, plus the transaction ID if there is one

For cost sync and name sync you'll also want the campaign, ad set and ad IDs in your tracking fields -- see [Dictionary sync](#dictionary-sync) below.

## Step 4: Map your events

Go to the **Conversion Tracking** tab and switch the toggle from **Classic Options** to **Integrations**.

![Integration Event Mapping for a Meta traffic source](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/05-meta-event-mapping_yo9zg6.png)

For each event you want Meta to receive:

1. Pick a **Triggering Event** -- **Conversions** or one of your custom events.
2. Pick a **Destination Event** -- one of Meta's standard events (Purchase, Lead, Complete Registration, Add to Cart and so on), or type your own name to send a custom event.
3. Optionally set a **Value Override**, **Currency Override** or webhooks.

Custom event names can only contain letters, numbers, underscores and hyphens -- any other characters are removed.

Each destination event can be used once per traffic source, so you can't accidentally send the same FunnelFlux event to Meta as two different events.

Note that saving in Integrations mode removes the traffic source's classic postback settings. If you're moving over from a Facebook custom scenario, make a note of your old setup first. See [Classic options vs Integrations](https://help.funnelflux.pro/en/article/using-traffic-source-integrations-s4p02b/#classic-options-vs-integrations) for why.

Save the traffic source when you're done.

## Step 5: Check events in Integration Logs

Go to Logs > Integration Logs. Every event we try to send to Meta is logged here with its outcome.

The **Included Data** column (turn it on via **Columns** > **HTTP Data**) shows which matching signals went with each event:

![Integration Logs filtered to Meta with the Included Data column](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/06-meta-integration-logs_6rodzg.png)

Click the tags in that cell to see the detail, including whether the Meta click ID (`_fbc`) was **constructed** from your fbclid field and whether the `_fbp` cookie was included or **omitted**:

![Included Data detail for a Meta event](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/07-meta-included-data-detail_16oci6z.png)

We don't calculate an Event Match Quality score -- Meta shows that in Events Manager for each event. But the more of these signals are included, the better Meta can match the event to a person. If Click ID is missing, fix your External Click ID tracking field first.

### The Queue view and held conversions

Switch the toggle at the top from **Event Logs** to **Queue** to see conversions that are waiting to be sent.

Each row shows the conversion's status (pending, processing, held, failed or completed), the hold reason, when the next attempt is due, and what to do about it.

If your Meta connection expires, gets disconnected or the integration is misconfigured, we don't throw the conversions away. They're **Held** with a reason such as **Credentials invalid** or **Configuration error**, and the Resolution column links you to the fix -- e.g. "Reconnect Meta integration".

Once you fix it (usually **Reauth** in Settings), held conversions are released and sent.

Note that Meta only accepts events up to 7 days old. Anything held longer than that can't be delivered and shows as **Expired while held** -- so fix connection problems promptly.

## Cost sync

Back on the traffic source's **Integrations** tab, the **Cost Sync** section pulls spend from your Meta ad account:

- **Enable campaign-level cost sync** -- imports campaign spend every hour.
- **Reconcile finalized daily costs** -- rechecks each finished day once Meta has finalized it (about 3 hours after the day ends in the ad account's timezone), so your costs match Meta's.

![Cost Sync and Dictionary Sync for a Meta traffic source](https://storage.crisp.chat/users/helpdesk/website/-/b/7/4/9/b749232d828ce800/03-meta-cost-and-dictionary-sy_qwivcp.png)

After saving, **Sync status** shows the last and next runs, with **Sync hourly costs now** and **Reconcile daily costs now** if you don't want to wait.

Note that native cost sync is campaign-level ONLY. For ad set and ad level costs, use Argosync -- click **Learn more** in that section.

## Dictionary sync

Meta passes IDs in your URLs, not names. **Enable ID to name sync** pulls your campaign, ad set and ad names from Meta and shows them in reports instead of the raw IDs.

For this to work, the IDs need to be in your tracking fields with these URL values (Source Token):

| Level | URL value |
|---|---|
| Campaign | `{{campaign.id}}` |
| Ad Set | `{{adset.id}}` |
| Ad | `{{ad.id}}` |

We match on the URL value, not the field name. The table in this section shows **Field present** for each level we can resolve -- if a row says **Add field**, add a tracking field with that value.

Turn on **Show original IDs after synced names** if you still want to see the ID next to the name.

## Troubleshooting

**My pixel isn't in the Dataset / Pixel list**

The Meta login you connected can't see it through the API. Either grant that user access to the dataset in Business Manager, or click **Enter ID manually**.

**Events don't show in Meta's Test Events**

Check the test code matches what Events Manager currently shows -- Meta generates new ones. Then check Integration Logs for a failed outcome and its error.

**Events arrive but match quality is poor**

Open Included Data in Integration Logs. If Click ID is missing, your External Click ID field isn't capturing `fbclid`. Passing email or phone to us (where you have consent) also helps a lot.

**Conversions stopped arriving**

Check Settings > Integrations > Traffic Sources for an Expired or Auth error status, then the Queue view for held conversions.