Facebook Pixel and Conversions API

Prefer to watch instead of read? Every step on this page also has a short video. They are bundled together at Facebook video guides - watch top-to-bottom to set everything up without reading.

Connect FacebookLink copied

Connecting Facebook is a Meta OAuth flow with five screens after you click the button in TrueMetriks. The whole thing takes about 90 seconds.

Video guide

Prefer to read along? The full step-by-step is below.

Step 1 - Click Connect Facebook in TrueMetriksLink copied

In the TrueMetriks dashboard, open Settings > Ad integrations, pick the Facebook tab, and click the highlighted Connect Facebook button.

A Meta OAuth popup opens. If your browser blocks popups, you will get an inline prompt to allow it - allow it and click Connect Facebook again.

Don't revoke this app in your Facebook Business Settings later. If you do, your Conversions API events stop firing until you re-run this flow. Use the Disconnect button in this card instead - it cleans up on both ends.

Step 2 - Confirm your Facebook accountLink copied

Meta asks which Facebook user is granting access. If you are signed into the right Facebook account, click Continue.

If the wrong account is shown (for example a personal account when you wanted a business one), click Log into another account and sign in. The Facebook user only needs profile-level access - this screen is just identity confirmation, no business permissions are granted here yet.

Step 3 - Choose which Businesses to shareLink copied

Meta now asks how much of your Business Manager footprint to give TrueMetriks. You have two options.

• Opt in to all current and future Businesses (recommended for most accounts) - TrueMetriks gets access to every Business portfolio on this Facebook account, including any you create later. Pick this if you run a single agency or own all the portfolios on this account.
• Opt in to current Businesses only - You will hand-pick which portfolios on the next view. Pick this if your Facebook account is a member of someone else's Business that you do not want TrueMetriks to touch.

Step 4 - Pick the Business portfolios (only if you chose "current only")Link copied

If you chose current Businesses only, Meta shows a searchable list of every Business portfolio your account belongs to. Tick the ones you want TrueMetriks to access. Use Select all to grab them in one click.

Each Business portfolio you select unlocks every ad account and every pixel inside it. You will pick the specific pixel for each TrueMetriks site in a later step (after the connect flow finishes).

Step 5 - Review the permission grantLink copied

Meta summarises what TrueMetriks is about to receive. There are three permissions and one summary line.

• Manage ads for ad accounts that you have access to - lets TrueMetriks read your ad account list and post events to the right pixel.
• Access your Facebook ads and related stats - lets TrueMetriks read campaign / ad-set / ad metadata so it can attribute clicks back to specific ads in the dashboard.
• Manage your business - lets TrueMetriks list pixels and catalogs inside the Business portfolios you selected. The line below ("2 Businesses selected" or similar) shows the count from Step 4.

Click Save when the list matches what you expect. If you spot the wrong scope, hit Back and re-do Step 3 or 4.

Step 6 - Confirmation, then back to TrueMetriksLink copied

Meta confirms the connection. Click Got it and the popup closes.

When the popup closes, the TrueMetriks dashboard card flips to Connected and reveals the next sub-section: Select your pixel. That is the next step below.

Select your pixelLink copied

The connect step gave TrueMetriks access to your Business portfolios. Now you tell it which pixel inside those businesses this site should fire events into. Three clicks.

Video guide

Prefer to read along? The full step-by-step is below.

Step 1 - Click Add pixelLink copied

Under the Active pixels header, click the highlighted Add pixel button in the top-right.

The hint banner shows how many pixels TrueMetriks found across the Business portfolios you connected. If the count is 0, your Business Manager has no pixel yet - create one in Facebook Events Manager first, then come back.

Step 2 - Pick the pixel from the dropdownLink copied

Clicking Add pixel inserts an empty row with a Pick a pixel dropdown. Click it to see every pixel in your connected Business portfolios. Each row shows the pixel name on the left and the Business / Ad Account it belongs to on the right.

Click the pixel you want. The dropdown closes and the row collapses to show your selection.

Step 3 - Review the Allowed events listLink copied

Click the row to expand it. Four sections appear: Pixel (the same selector, in case you want to swap), Test event code (covered in How to test), Allowed events (highlighted), and Custom events (covered later).

How the Allowed events list works

All seven standard Facebook events (PageView, ViewContent, AddToCart, InitiateCheckout, Lead, Schedule, Purchase) are checked by default. A checked box does not make an event fire - it just means "if my site fires this event, send it to this pixel." Which ones actually fire depends on your site and platform.

Leave all seven checked unless you are in a restricted category (health, wellness, finance, and similar) where Meta blocks certain standard names. In that case, uncheck the restricted standard here and fire a custom event in its place (see Custom events below).

Click Save changes at the bottom of the integration card to persist your pixel selection and the allowed-events list.

Custom eventsLink copied

The Allowed events list above controls which standard event names go to your pixel. Custom events let you fire an additional, custom-named event alongside any standard event. Two reasons to use them:

1. Granular reporting - mirror Purchase as Purchase_NewCustomer for new-vs-returning splits, or Lead as Lead_Webinar to break out a specific lead source. Both events fire; the standard one keeps your existing optimization audiences healthy and the custom one gives you a dedicated reporting column in Ads Manager.
2. Restricted-category bypass - if your business is in a category Meta restricts (health, wellness, finance, supplements, gambling, dating, alcohol, and a few others), Meta will block or throttle ad delivery on certain standard event names like Purchase, Lead, InitiateCheckout, AddToCart, Schedule, and ViewContent. In practice you are stuck with PageView for optimization, which is too high in the funnel to be useful. The workaround is to uncheck the restricted standards in the Allowed events list above and instead fire a custom event with a meaningless name (e.g. ghyu) that Meta's pattern detector cannot map back to a restricted intent. For the full strategy - including how to keep your product names and URLs just as neutral as the event name - see the dedicated Restricted categories guide. A blog post on which categories are restricted and how Meta enforces it is coming too; we'll link it here when it ships.

Explainer video

Walkthrough - restricted categories

If your business sits in a restricted category, the video below walks through the exact "uncheck the restricted standards, fire a custom event with a neutral name" pattern from point 2 above, end-to-end in TrueMetriks.

Explainer video

For the full playbook - including how to keep your product names and URLs just as neutral as the event name - see the dedicated Restricted categories guide.

Step 1 - Click CreateLink copied

Inside the expanded pixel row (the same one where the Allowed events checkboxes live), scroll to the Custom events panel and click the highlighted Create button in the top-right.

Step 2 - Fill in the Create custom event popupLink copied

Clicking Create opens the Create custom event popup. It has three fields, plus an optional fourth that appears only for Purchase:

• Standard event (dropdown) - the standard event you want to mirror. Pick Purchase to fire every time a Purchase event would. Same for Lead, Schedule, etc.
• Custom event name (input) - any name you want. It must start with a letter and can contain letters, numbers, spaces, _ or -, up to 40 characters. For restricted categories, use something arbitrary and meaningless like ghyu, kt8x2, or wellness_evt_a - anything that does NOT contain the words purchase, buy, cart, checkout, lead, signup, etc. For granular reporting, use something descriptive like Purchase_NewCustomer or Lead_Webinar.
• Fire when (dropdown) - Always (the default) fires on every matching event. For Purchase, Lead, and Schedule you can also pick New customers only or Returning only to split your audience.
• Product filter (Purchase only, optional) - fire only when a purchased product matches a name or ID. Leave it blank to fire on every Purchase. See the Product filter section below.

Then click the highlighted Create button.

Step 3 - Save changes to create it in FacebookLink copied

Your new custom event appears as a card in the Custom events list with a coloured status dot. It starts amber ("unsaved - click Save changes") until you persist it.

Click the Save changes button at the bottom of the integration card. TrueMetriks calls the Meta API and creates the matching Custom Conversion in Facebook for you; the dot turns green and a synced check mark appears.

To change a saved custom event later, click the pencil to edit when it fires (or its product filter). The standard event and custom name lock once it is saved, so to rename one, delete it with the trash icon and create a new one.

Step 4 - Confirm the Custom Conversion appears in FacebookLink copied

The moment you save, TrueMetriks calls the Meta API and creates a Custom Conversion in Facebook on your behalf. You don't have to set it up manually.

To confirm it landed, go to Meta Ads Manager → Events Manager (left rail) → pick the pixel you mapped this to → Custom conversions tab. Your custom name shows up in the table, attached to the right pixel and Ad Account.

It will be Inactive until the first event lands. Fire a test event (covered in How to test below) or wait for live traffic; the status flips to Active once Meta sees the first conversion.

Step 5 - Add the conversion as a column in Ads ManagerLink copied

A Custom Conversion is only useful if you can see it in your campaign reporting. In Meta Ads Manager → Campaigns (or Ad sets / Ads) → click the Columns: Performance dropdown in the top-right → pick Customize columns at the bottom of the menu. Search for your custom name, tick Total, Value, and Cost on the matching row, then click Apply.

Step 6 - Read the column on every campaign rowLink copied

The Campaigns / Ad sets / Ads table now has a dedicated column for your custom conversion. Use it the same way you would use a standard Purchase column - sort by it, build saved reports off it, set up automated rules against it.

Important gotchasLink copied

• Wait 30 to 60 seconds after Save before firing test events. Meta needs to finish creating the Custom Conversion before it will accept matching events. If you fire too fast, the first few events will land as plain custom events without the conversion attached.
• Removing a custom event in TrueMetriks does NOT delete the Custom Conversion in Facebook. It stops TrueMetriks from firing the custom name, but the Custom Conversion entry stays in Events Manager. If you no longer need it, delete it from Facebook's Custom Conversions tab manually.
• Custom Conversions have a 100-per-pixel limit (Meta's restriction, not ours). Each custom event you add counts as one. The Custom Conversions list in your pixel will show "You have N custom conversions remaining" at the bottom.

Product filterLink copied

The Product filter is an optional control on a Purchase custom event. It lets you fire the custom event only when a specific product was bought, instead of on every Purchase. It appears in the Create custom event popup whenever the standard event is Purchase.

Video guide

You have two fields, and they are either/or - a purchase fires the event if it matches either one:

• Product name (contains) - a case-insensitive contains match on the product name. Enter Masterclass and a product called "Ultimate Ads Masterclass" matches, because its name contains that word.
• Product ID (exact) - a case-insensitive exact match on the product's ID or SKU.

Fill in one, the other, or both. If any purchased product in the order matches either field, the custom event fires. Leave both blank and the event fires on every Purchase, the same as not using the filter at all.

Why this is usefulLink copied

A product filter lets you optimize and report on a single product instead of "any purchase". For example, if your funnel has an upsell with a strong take rate, create a Purchase custom event filtered to that upsell product, add it as a column in Ads Manager, and optimize your campaigns toward that specific conversion - so Meta learns to find buyers of your best upsell, not just any buyer.

CatalogLink copied

A Facebook Catalog is the product database Meta uses to power Advantage+ catalog ads (dynamic product ads, retargeting carousels, Instagram shops). Connecting your catalog to TrueMetriks lets Meta match every Purchase, AddToCart, and ViewContent event we ship against a specific product in your catalog, so dynamic-product-ad audiences populate correctly.

This step is mostly useful if you sell physical products on Shopify or WooCommerce. If you only run lead-gen or info-product campaigns, you can skip the catalog entirely - the Purchase / Lead events will still attribute back to your ads through the pixel selection above.

What you need before connectingLink copied

Meta's catalog format requires a few fields on every product. Most ecommerce platforms generate this automatically when you install their Facebook integration (covered below per-platform):

• id - a unique product identifier per item, usually your SKU.
• title - product name.
• description - product description.
• availability - one of in stock, out of stock, preorder, available for order, discontinued.
• condition - one of new, refurbished, used.
• price - amount + ISO currency, e.g. 29.99 USD.
• link - public URL of the product page.
• image_link - public URL of the main product image. Minimum 500x500 pixels, 1024x1024 recommended, JPEG or PNG, under 8 MB.
• brand - manufacturer or brand name.

If your catalog is missing fields, products with bad data are excluded from Advantage+ ads and your catalog match rate drops.

Video guide

Prefer to read along? The full step-by-step is below. The Shopify-specific catalog flow has its own walkthrough further down.

Step 1 - Click Connect Facebook CatalogLink copied

In TrueMetriks, scroll down to the Facebook Catalog panel inside the Facebook integration card and click the highlighted button.

This triggers a second Meta OAuth grant, separate from the one that connects your pixel. Catalog access is a different permission scope, which is why Facebook asks again.

Step 2 - Authorize through Meta OAuthLink copied

A separate Meta popup opens for the catalog grant. It walks you through four screens.

Confirm your Facebook account. Click Continue.

Choose which Businesses to share. Same scope choice as the pixel connect: opt in to all current and future, or pick specific Business portfolios. Pick whichever is appropriate and click Continue.

Review the permission grant. The catalog grant asks for two things the pixel grant did not: a new top-line permission Manage your product catalogs, plus a Review what terms you are agreeing to → Product Catalog Terms section. Read them, then click Save.

Connection confirmed. Click Got it to close the popup. The TrueMetriks panel reloads.

Step 3 - Create a new catalog or connect an existing oneLink copied

After OAuth closes, the panel in TrueMetriks switches to a catalog picker:

• Create new catalog (recommended) - TrueMetriks creates a fresh catalog named TrueMetriks - your-domain.com inside the Business portfolio you picked. Use this if you don't already have a catalog or if you want a clean separation between TrueMetriks-tracked products and any other catalog you run.
• Connect to existing catalog - pick a catalog from the dropdown. Use this if Shopify, WooCommerce, or another partner already populates a catalog you want to keep.

Click Connect catalog. TrueMetriks saves the choice and the panel flips to "Catalog connected".

Step 4 - Find your catalog in Meta Commerce ManagerLink copied

Catalogs live in Meta's Commerce Manager, not Ads Manager. Open Commerce Manager → pick the same Business portfolio you connected → Assets in the left rail → Catalogs. Your new catalog appears in the list.

Click into the catalog to open its dashboard. Catalog → Products in the left rail shows every item the catalog knows about; on a fresh catalog this list is empty until your platform (Shopify / WooCommerce / a feed URL) starts pushing products in.

Step 5 - Connect the pixel as the catalog's event sourceLink copied

A catalog is just product data until you wire it to a pixel. Meta uses the pixel to learn what your visitors viewed, added, and bought, and matches those events to catalog products via the content_ids field on each event.

On the catalog Overview screen, the Connect to tracking row will be red until you do this. Click Connect event source (highlighted), or use Catalog → Events in the left rail.

A dataset picker opens. Flip the toggle on the same pixel you picked in Select your pixel above, then click Connect.

Meta now knows which pixel to listen to for catalog matching.

Step 6 - Watch the catalog match rate climbLink copied

The Events tab now shows your dataset with a Catalog match rate gauge.

The match rate is the share of Purchase / AddToCart / ViewContent events whose content_ids actually map to a product in this catalog. It starts at 0% the moment you connect (no events have arrived yet under the new wiring) and climbs as live traffic flows in. Aim for 90%+ within a day or two of normal traffic; anything below 90% means a chunk of your events are firing IDs that don't exist in the catalog, which usually points to:

• The pixel events ship Shopify variant_id but the catalog stores product_id (or vice versa).
• Some products are missing from the catalog feed entirely.
• Newly added products haven't synced yet (Shopify / Woo feeds typically refresh every 1-24 hours).

The Catalog → Events screen has a per-dataset diagnostics view that lists the most-common unmatched IDs - work through those to lift the score.

Connect a catalog on ShopifyLink copied

On Shopify, the TrueMetriks Catalog Sync app handles everything end-to-end - just like on WordPress, you do not need Meta's "Facebook & Instagram by Meta" sales channel. Install the TM app once, and every product create / update / delete in Shopify pushes to the catalog you connected in Step 3 above. Initial sync runs automatically the moment the install completes.

This connection is separate from the Facebook OAuth you did earlier - it grants TrueMetriks read access to your Shopify products, which lets us push them into the Facebook catalog.

Video guide

Prefer to read along? The full step-by-step is below.

Step 1 - Open Shopify Admin Settings

Inside your Shopify Admin, click Settings in the bottom-left of the sidebar.

Step 2 - Click Domains

Inside Settings, scroll the store sub-menu and click Domains.

Step 3 - Copy the .myshopify.com domain

You will see two rows: your custom storefront domain (marked Primary) and the original Shopify-issued domain that ends in .myshopify.com. Copy the .myshopify.com row, not the primary one.

TrueMetriks identifies Shopify stores by their permanent .myshopify.com handle, so the primary domain will not work even if it points to the same store.

Step 4 - Paste it into TrueMetriks and click Connect Shopify

Switch back to the TrueMetriks dashboard, scroll to the Connect Shopify (for FB Catalog sync) panel inside the Facebook integration card, paste the .myshopify.com domain into the input, and click Connect Shopify. The button starts spinning and a small popup window opens.

Step 5 - Install the TrueMetriks Catalog Sync app

The popup is Shopify's standard install prompt. The app is TrueMetriks Catalog Sync and asks for only two scopes: View store data: Products (so we can read your product list) and View staff and contributor data: Store owner. Click Install.

Once you click Install, Shopify provisions the access token, the TrueMetriks backend receives it, and the popup closes itself. The TrueMetriks panel updates inline to Connected to your-store-abc123.myshopify.com. Shopify product catalog sync is active. without reloading the page.

Step 6 - Sync is automatic from this point

The moment the install completes, TrueMetriks pulls your entire Shopify product catalog and pushes it into the Facebook catalog you picked in Step 3 above. Every subsequent product create, update, or delete in Shopify is forwarded in real time through the same webhook pipeline - no scheduled cron, no manual re-imports.

You do not need to do anything else. The pixel events fired by the Shopify Custom Pixel (the one you set up in Select your pixel above) ship content_ids that match the Shopify product IDs in the catalog, so dynamic-product-ad audiences populate as soon as live traffic flows in.

Same automatic-sync model on WordPress: the TrueMetriks WP plugin handles all create / update / delete events through WooCommerce hooks. No manual sync is required on either platform.

Field mapping note: the TrueMetriks Catalog Sync app ships variant_id as the catalog id for variant-level products and product_id for simple products. The TrueMetriks Shopify Custom Pixel emits matching content_ids automatically. If you ever wire a non-TM pixel to the same catalog, double-check it ships the same ID shape or your match rate will drop.

Connect a catalog on WordPress / WooCommerceLink copied

On WordPress + WooCommerce, the TrueMetriks plugin handles the catalog sync end-to-end - you don't need Meta's "Facebook for WooCommerce" extension at all. The TrueMetriks plugin pushes products into the catalog you connected in Step 3 above, so there's nothing to wire up manually on Meta's side.

How it works

1. You connect the Facebook Catalog in the TrueMetriks dashboard (Steps 1-3 above) - that's the only place the OAuth + catalog selection happens.
2. The TrueMetriks WordPress plugin polls your TrueMetriks account, detects the connection, and starts pushing products into the connected catalog automatically.
3. Every time you create, update, or delete a product in WooCommerce, the plugin syncs that change to the catalog in real time. No cron, no scheduled re-pushes.

That means you do not need to repeat the Facebook OAuth inside WordPress. The dashboard connection covers both the pixel events and the catalog feed.

Before connecting on the dashboard

Open WordPress Admin → TrueMetriks → Facebook Catalog. Before the dashboard connection is in place, the tab looks like this:

The Status line confirms the catalog isn't connected yet. The blue Connect Facebook Catalog button just deep-links you straight to the right page on the TrueMetriks dashboard - it doesn't run any OAuth on the WordPress side.

After connecting on the dashboard

Once you complete the connect flow in the dashboard (Steps 1-3 above), the WordPress plugin auto-detects the change on its next poll. If the WordPress tab was already open, click Refresh connection status to force a re-check immediately. The green banner appears and the tab switches to the connected layout:

You now have three actions on this tab:

• Refresh connection status - re-fetches the connection state from your TrueMetriks account. Useful right after connecting in the dashboard, or if you ever suspect WordPress and the dashboard have drifted apart.
• Default brand - Meta requires a brand field on every catalog product. The plugin reads brand from WooCommerce taxonomies (product_brand, pwb-brand, yith_product_brand) when available; this fallback value is used for any product that doesn't have one. Leave blank to use your WordPress site name as the fallback.
• Resync all products - forces a full re-push of every product in your WooCommerce catalog into the Facebook catalog. Normal create / update / delete events sync automatically; only use Resync after a sync error or a Meta-side rebuild.
• Disconnect - stops the WordPress plugin from pushing further updates and removes the catalog binding. The dashboard-side connection stays in place; reconnect the WordPress side later with Refresh connection status.

What you should NOT do

You do not need to install Facebook for WooCommerce alongside the TrueMetriks plugin. If you already have it, that's fine - it'll create its own duplicate catalog. Just make sure the catalog you pick in the TrueMetriks dashboard (Step 3) is the TrueMetriks-managed one, not the Facebook-for-WooCommerce-managed one. Pointing TrueMetriks at the wrong catalog will work, but you'll end up syncing the same products twice into different catalogs.

Field mapping note: the TrueMetriks plugin ships the WooCommerce product_id (or variation_id for variable products) as the catalog id, and the TrueMetriks tracker fires matching content_ids on Purchase / AddToCart / ViewContent events. Catalog matching works without any extra configuration.

Other platformsLink copied

If your store runs on BigCommerce, Squarespace Commerce, Wix, or a custom build, the path is:

1. Use Meta's Data Sources flow in Commerce Manager (Catalog → Data sources) to point Meta at a product feed URL or CSV / XML upload.
2. Or use a feed-management tool (DataFeedWatch, GoDataFeed, Channable) to generate and push a feed.
3. Connect that catalog in TrueMetriks using the Connect to existing catalog path.
4. Make sure whatever fires your Purchase / AddToCart / ViewContent events ships content_ids that match the id field in the feed.

Lead forms and DM adsLink copied

Connect your Facebook Page and TrueMetriks records every native lead form submission and every click-to-message conversation as a conversion, attributed to the exact ad, ad set and campaign, so cost per lead lands in the reports you already use.

Facebook and Instagram let you run two kinds of ad where the person never reaches your website: a lead form ad (a native Instant Form they fill in without leaving Facebook or Instagram) and a DM ad (a click-to-message ad that opens a Messenger or Instagram Direct conversation). There is no page to put a tracking script on, so TrueMetriks could not see either one. Connecting your Page is what makes them visible, and it is the only setup there is.

What gets recordedLink copied

Two conversions, with these exact names:

• Lead - Facebook Form - one per native lead form submission. It carries the submitter's email, so the person is stitched to the rest of their journey the same way any identified visitor is.
• DM Started - one per person per ad who opens a Messenger or Instagram Direct conversation from a click-to-message ad.

Both appear in Conversions Overview with no filter selected, and both can be filtered by name, so a lead taken on a Facebook form stays distinguishable from a lead taken on your website. Either name can also be mapped to a Facebook custom conversion in Custom events above.

Two more behaviours worth knowing about:

• If someone types their email into the DM thread, or completes a lead form inside the chat, TrueMetriks links that conversation to the person. The ad that started the chat still gets the credit when they buy on your website days later. Both routes work on Messenger and on Instagram Direct, and neither happens by itself: see How the person's email reaches you below for what you have to build into the ad.
• Comments on your ad posts are matched back to the ad that carried the post. That needs nothing beyond connecting the Page, and it is the foundation for comment-keyword automation.

Connect your PageLink copied

It is the same Meta OAuth popup you went through for the pixel, plus two screens of its own: one asking which Page to grant, then one asking which Instagram account. Seven steps, about 90 seconds. You choose the Page once, on Meta's screen - TrueMetriks connects what you granted and never asks you to pick it again.

Step 1 - Click Connect a Page in TrueMetriks

In the TrueMetriks dashboard, open Settings > Ad integrations, pick the Facebook tab, and scroll to the Connect your Page block at the bottom of the card, below Catalog. Click the highlighted Connect a Page button.

Facebook has to be connected first. If it is not, the button is greyed out and reads "Connect Facebook above first", so run Connect Facebook at the top of this page before this. The button is also disabled until your tracking domain is verified, because a Page connected on an unverified site would record nothing.

Step 2 - Confirm the Facebook account granting access

Meta asks which Facebook user is granting access. If you are signed into the right account, click Continue. This is the same first screen as the pixel connect.

Step 3 - Choose which Businesses to share with TrueMetriks

Meta asks how much of your Business Manager footprint to share. Opt in to all current and future Businesses is the lowest-friction choice. Opt in to current Businesses only lets you hand-pick, and adds the portfolio list in the next step.

Step 4 - Pick the Business portfolios for the Page

Only if you chose "current only". Meta lists every Business portfolio your account belongs to. Tick the one that owns the Page running the ads, or use Select all.

Step 5 - Choose the Page and the Instagram account to grant

This is the part the pixel connect never showed you, and the one that decides everything. It is two screens, one after the other.

Screen one lists your Pages. Tick the Page that runs the ads. A lead form ad and a click-to-message ad are attached to a Page, and if you grant a different one, nothing arrives and nothing errors to tell you. Then click Continue.

Screen two lists your Instagram accounts, as handles rather than Page names, so nothing on it looks like the Page you just ticked. Tick the Instagram account that runs the ads if you want Instagram DM ads or Instagram comments tracked, then click Continue again.

Clicking through that second screen without ticking anything is the single most common way Instagram ends up recording nothing, and no screen anywhere will tell you it happened.

This is where you pick the Page. TrueMetriks connects what you granted here, so the old step of choosing it again inside the dashboard is gone. Grant the one Page that runs the ads and there is nothing left to decide. Instagram needs three settings of its own on top of this grant: see What you must set up on the Instagram side below.

Step 6 - Review the permissions

The review screen lists more than the pixel grant did, because reading a lead form and receiving a Messenger conversation are separate permissions from reading ad stats. In plain terms you are letting TrueMetriks see the Pages you manage, manage the settings on the Page you picked, read its lead form submissions, receive its Messenger conversations, and, if you ticked one, read the messages and comments on the Instagram account linked to it. Click Save.

Step 7 - Confirmation, then back to TrueMetriks

Meta confirms the grant. Click Got it, the popup closes, and the Page you granted is connected to this site on its own. There is nothing further to pick.

A Page can only belong to one site. If the Page you granted is already connected to another of your sites, TrueMetriks tells you so instead of connecting it, and nothing is moved.

What you see when it is done

The card lists your Page with a green Active chip, the capability chips light up, and the counters start at 0 leads / 0 DMs recorded. They climb on their own as leads and conversations arrive, with no further setup.

If the Active chip is replaced by Reconnect needed, the Page token has gone stale. That happens when the app is revoked in your Facebook Business Settings, or when the Facebook password changes. The capability chips turn amber and read "Lead forms paused" and "Messenger ads paused", and nothing new is recorded until you click Reconnect and run the dialog again. Conversions already recorded are kept.

What you must set up on the Instagram sideLink copied

Instagram DM ads and Instagram comments ride the Instagram account linked to the Facebook Page you just connected, never Instagram on its own. Three things on your side decide whether anything arrives at all, and none of them produce an error message when they are wrong. They produce silence, which is far harder to spot.

1. The Instagram account has to be a professional account, linked to that Page. A personal Instagram account cannot be reached by any connected tool, so switch it first in the Instagram app (Settings and privacy > Account type and tools > Switch to professional account, either Business or Creator). Then link it to the Facebook Page that runs the ads.

You can check the link from inside TrueMetriks rather than hunting for it: on the connected Page, the Instagram DM ads chip turns green and shows the handle (Instagram DM ads - @demo_brand) as soon as we can see a professional account linked to that Page. A muted chip with a dash means we found none, and that is the first thing to fix.

2. Allow access to messages has to be on. Instagram keeps its own switch for whether connected tools may read the account's messages, separate from anything you agreed to on Facebook. It is off on plenty of accounts.

3. The account has to be public, for comments. Meta only sends comment notifications for public content, so a private Instagram account means comments on your Instagram ads are never recorded. Direct messages still work.

Two more, both easy to miss. The Instagram account has to be ticked on the second grant screen when you connect, the one that lists Instagram handles after the Pages screen (Step 5 above) - granting the Page alone leaves Instagram out. And you need admin access to both the Facebook Page and the Instagram account: if somebody else owns the Instagram account, they have to make the changes above.

How the person's email reaches youLink copied

A conversion is only half the job. The email address is what ties a lead form or a conversation to the same person when they come back and buy on your website, and how you get one is different on every surface. This is the part most people miss.

Facebook and Instagram lead forms: use Meta's built-in Email field. An Instant Form asks for the email itself and Meta pre-fills it from the person's profile, so the address arrives with the lead. One thing decides whether it identifies the person: when you build the form, the email has to be Meta's own Email question, the one under Contact information in the form builder, and not a custom question you typed yourself. A custom question worded "What is your email address?" is still saved on the conversion, but it does not become the person's identity, so the lead never stitches to their later purchase. Same rule for the phone number: pick Meta's Phone number field. With the built-in fields in place, lead forms are the most reliable of the three.

Messenger DM ads: put a lead form inside the chat. A click-to-Messenger ad only produces an email if you built one into the ad's message template. In Ads Manager, open the ad's message template, pick the Generate leads chat template (Meta also labels it lead generation in chat, inside the automated chat templates), and add a question asking for the email address. Word the question so it contains the word "email", and Meta will only accept an email-shaped answer to it.

The person has to finish the flow. When they do, the answers come to us with the conversation and the DM Started conversion carries their email. If they abandon it half way, or the template has no email question at all, the conversation is still recorded and still attributed to the ad, but the person stays anonymous until they type an address into the thread themselves.

Instagram DM ads: you have two ways, and you should use both. Instagram is the one surface where the email can arrive by either route, so do not rely on a single one.

Way one, a lead form inside the chat. If Ads Manager offers the Generate leads chat template for your Instagram click-to-message ad, build it exactly as you would for Messenger and put an email question in it. Meta does not offer that template for every ad type, objective or country, so open the ad's message template and look before you assume it is there. It is the same screen as the Messenger mockup above. When the person completes it, the answers reach us with the conversation and the DM Started conversion carries their email, identical to Messenger.

Way two, ask them to reply with it. This is the fallback whenever the chat template is not available, and it is worth doing even when it is, because plenty of people never finish a form. Ask for the address plainly in the ad's opening message or in your first reply, and we read it out of what they type back.

What counts as an email, when someone types one. We read an address out of a chat message only for people who arrived from one of your ads, and we read nothing else from the conversation. Four rules decide what we accept, and they are worth knowing because they explain the odd miss:

• The first address wins, permanently. If someone types a colleague's address first and their own second, the first one is the one we keep.
• Your own domain is ignored. "I already emailed [email protected]" is somebody quoting your address back at you, not giving us theirs.
• An address inside a link is ignored. It is a tracking parameter, not a person.
• Very long messages are not scanned. Nobody types their email inside an essay.

Learning who somebody is does not create a second conversion. The DM Started you already have simply stops being anonymous, and every later touch, including a purchase on your website weeks afterwards, lands on the same person and credits the ad that started the conversation.

Comments on your ads, and comment-to-DM adsLink copied

Anyone who comments on one of your ad posts is recorded against that exact ad, on Facebook and on Instagram, with nothing to set up beyond connecting the Page. Comments on organic posts are not recorded, because there is no ad to attribute them to.

That matters most if you run the engagement play: an ad that invites people to comment a keyword, and Meta's ad-level automation that answers each of them with a private message.

The thing to understand is what a comment does and does not tell us. It tells us the ad and the person. It never contains an email address, and Meta does not hand one over. So the private message is where the identity is won or lost: write it to ask for the email, exactly as you would in an Instagram DM ad, and the moment they reply with one, that commenter becomes a person you can follow to the sale.

Two limits on comments, both Meta's:

• Catalog and dynamic ads carry no ad id on Instagram comments. A comment on one of those is not attributed and is not recorded.
• A private Instagram account sends no comment notifications at all. See the Instagram setup above.

Disconnecting a PageLink copied

Disconnect removes the Page from TrueMetriks and unsubscribes it on the Facebook side, so new leads and DMs stop being recorded immediately. It is one click behind a confirmation, and conversions already recorded are not deleted. You can connect the same Page again later.

What to do on Facebook's side, in one listLink copied

There is no pixel to add to the ad, no parameter and no UTM, and lead form and click-to-message ads that are already live start reporting the moment the Page is connected. What does need your attention:

• Connect the Page that runs the ads. Both ad types are attached to a Page. Connect a different Page and nothing arrives, and nothing errors to tell you.
• Get an email out of every DM ad, both ways. Put an email question in the ad's Generate leads chat template where Ads Manager offers one, on Messenger and on Instagram alike, and ask for the address in the opening message as well, because plenty of people never finish a form.
• On a lead form ad, use Meta's built-in Email field, the one under Contact information in the form builder. A custom email question you typed yourself is recorded but does not identify the person.
• Ask for the email in the private message your keyword automation sends to commenters.
• Set up Instagram once: tick the Instagram account on Meta's grant screen, and on Instagram's side a professional account, linked to that Page, with Allow access to messages on and the account public.
• Keep the Page connected. If the app is revoked in your Facebook Business Settings, or the Facebook password changes, the Page shows Reconnect needed and records nothing until you run the dialog again.

Good to knowLink copied

• Instagram DM tracking also waits on Meta. Beyond the three Instagram settings above, the connect flow asks Facebook for two Instagram permissions that are still in review, so Instagram conversations start reporting once that lands. Do the Instagram setup now and there is nothing left to do when it does. Facebook lead forms and Messenger DM ads do not depend on it.
• WhatsApp is not supported yet. Its chip is muted on purpose rather than broken.
• These conversions are never sent back to Facebook. Facebook already counts its own lead forms and DM ads natively, so re-sending them through the Conversions API would double count them. The one exception is a name you explicitly map to a Facebook custom conversion.
• Some leads arrive with no ad attached and show as unattributed. Meta's documented reasons: the lead came from an organic post rather than an ad, it came from an Ad Preview, or the Facebook account you connected does not have advertiser access on the ad account.
• A DM tells us a person, not an email address. You get an identified lead out of a conversation only when they type an email into the thread or complete a chat lead form that asks for one, on either Messenger or Instagram, and then a later purchase on your website carries the ad credit. A lead form ad carries the email as long as you used Meta's built-in Email field. See How the person's email reaches you above.
• One Page belongs to one site. If the Page you granted is already connected to another of your sites, TrueMetriks says so and connects nothing. Disconnect it there first, or grant a different Page.
• Your tracking domain must be verified first. A site without a verified CNAME cannot connect a Page, and the button stays disabled with a hint, because a Page connected on such a site would silently record nothing.

How to testLink copied

Before you trust the pixel for real campaigns, you want to see your events arrive in Facebook with your own eyes. Meta's Test Events tab is the way - and TrueMetriks has a one-field workflow that wires it up. Six steps, about two minutes end-to-end.

The whole loop: copy a short-lived test code from Facebook, paste it into TrueMetriks, browse your site, watch events appear in real time on Facebook's Test Events table. After 24 hours the code expires and your events automatically flow back into the live Facebook feed - no flag to clear.

Video guide

Prefer to read along? The full step-by-step is below.

Step 1 - Click Open in Facebook in TrueMetriksLink copied

Expand your pixel row in Settings > Ad integrations > Facebook. In the Test event code group, click the highlighted Open in Facebook link.

This opens Facebook Events Manager in a new tab, scoped directly to the pixel you are working on. No hunting through the Meta UI to find the right dataset.

Step 2 - You land on Datasets, with your pixel selected and the Test events tab activeLink copied

Facebook Events Manager opens straight to Datasets, with the pixel from TrueMetriks highlighted in the middle list and the Test events tab already selected in the right panel.

If you have multiple pixels, double-check the name in the right-panel header matches the pixel you clicked from in TrueMetriks. The first time you open this tab on a fresh pixel, the channel dropdown reads Select channel - that's the next click.

Step 3 - Pick Website in the Select channel dropdownLink copied

Click the Select channel dropdown and choose Website.

Always Website, never Offline. TrueMetriks sends every event over the Conversions API as a website event - even server-fired Purchases. The Offline option is for CRM uploads and won't show your test traffic.

Step 4 - Copy your unique test codeLink copied

Once you pick Website, Facebook reveals a Confirm your server's events are set up correctly card. The first step inside that card shows your unique test code as a test_event_code: TEST... chip with a Copy button next to it.

Click Copy. That's the only thing you need from this card - ignore the Graph API Explorer button and the "Confirm your website's events are set up correctly" card below it, those are for raw API testing and we already handle the server side for you.

Step 5 - Paste the code back into TrueMetriks and saveLink copied

Switch back to TrueMetriks, paste the code into the Test event code field, and save. The pixel-row header flips to a green Test active - 24h left badge.

From this moment on, every event TrueMetriks sends for this pixel carries the test code attached. Facebook routes those events into the Test Events tab instead of your live feed, so nothing you do in the next 24 hours will dirty your production reporting.

You only need to do this for the pixel you are actively testing. Other pixels with no test code keep sending real events to production - they are not affected.

Step 6 - Browse your site and watch events arriveLink copied

Go to your website and do something that should fire an event. Open a few pages (PageView), add a product to cart (AddToCart), start a checkout (InitiateCheckout), submit a lead form (Lead), or place a test order (Purchase).

Switch back to Facebook Events Manager. Within a few seconds the Receiving activity banner turns green and rows start appearing in the table, newest at the top.

Every row carries the event name, a green Processed pill, the Event ID, and the timestamp. Watch them stack up as you browse.

Every row says Server under Received From. That is correct and expected. TrueMetriks is server-side only - we do not fire the Facebook browser pixel at all. Every event you see in Test Events came from our server talking directly to Meta's Conversions API, with click IDs and hashed PII attached. The "Server" pill on every row is the proof.

If you don't see events within ~30 seconds, jump to Troubleshooting below.

After the test - the code expires automaticallyLink copied

Test codes are deliberately short-lived. 24 hours after you saved it, the code expires and TrueMetriks resumes sending events to your production Facebook feed without any action from you. The green badge in the pixel row disappears and the field empties out.

If you want to end the test sooner - say you confirmed everything in 5 minutes and don't want a 24-hour gap in production reporting - just clear the Test event code field in TrueMetriks and save. Events flow to production from the next event onward.

TroubleshootingLink copied

Events show up on Test Events but never appear in campaign reporting. Test events are scoped to the Test Events tab only - they are intentionally walled off from your live attribution. After the code expires (or you clear it), real events flow to production. Check campaign reporting the day after, not during the test.

Receiving activity stays empty for more than a minute. Three things to check, in order: 1. The pixel name in the Facebook Events Manager header matches the pixel you pasted the code into - mismatched pixels are the most common cause. 2. Your Channel dropdown says Website, not Offline. 3. The test code in TrueMetriks matches the one in Facebook character-for-character. If a code is older than 24 hours, Facebook silently ignores it - copy a fresh one from Step 4 and re-paste.

Events arrive but the Catalog match rate stays at 0%. Your event content_ids don't match the IDs in your catalog feed. See the Catalog section above - on Shopify the catalog ID is the variant id, on WooCommerce it is the product id. Cross-reference one event's content_ids against the catalog's product list in Commerce Manager.

The Test active - 24h left badge never appeared after saving. The code field didn't take. Hard-refresh the dashboard page, re-paste the code, and save again. If it still doesn't stick, the saved code is probably one that already expired in Facebook - get a fresh one.