Ads conversion tracking (Meta CAPI)

Overview

The platform already captures paid traffic: click-to-WhatsApp ads (CTWA), ads that open a conversation in Messenger (click-to-Messenger) or Instagram Direct (click-to-Instagram Direct) and lead-form leads (leadgen) arrive attributed to their source campaign. Conversion tracking is the other side of that loop: it sends back to Meta the events that happen afterwards — a captured lead, a first contact, a closed sale — through the Conversions API (CAPI).

With it, Meta can optimize campaigns on real outcomes (not just the click), and you measure cost per conversion and return on ad spend with real data.

Key points:

• Configuration is per inbox (each WhatsApp/ads inbox has its own destination).
• Events are deduplicated by a deterministic identifier — the same sale is never counted twice.
• The token never appears in the UI (only its presence and the last 4 characters).
• The active provider today is the Meta Conversions API; Google Ads and TikTok exist as prepared scaffolding but do not send events yet.

Capture (CTWA/leadgen) and conversion are distinct modules. This article covers only sending events back to Meta. For capture and attribution, see the Ads/CTWA/leadgen article.

Prerequisites

• Opt-in module: your account needs the ads_conversion_tracking flag enabled. It is different from the capture flag (growth_ads) — you can have capture without conversion sending.

• Administrator permission (all configuration and manual triggering are admin-only).

• An inbox on a Meta channel and a token with that channel's events permission:

  • WhatsApp Cloud: the WhatsApp Business Account (WABA) and whatsapp_business_manage_events;
  • Messenger (Facebook Page inbox): the Page and page_events;
  • Instagram: the Instagram professional account and instagram_manage_events.

  WhatsApp Web, 360dialog or Twilio inboxes have no WABA — in those cases the Dataset ID and token are entered manually.

• The Page and Instagram logins don't ask for page_events or instagram_manage_events. For Messenger and Instagram, use the token of the Meta Ads Manager connection (its permissions come from your Facebook Login for Business configuration in the Meta App Dashboard) or paste a token that has the permission.

• Dark-ship: when created, the configuration starts off (enabled = false). Nothing is sent until you flip the switch — by design, so you validate first.

Step by step

1. Open the Inbox Settings for the inbox you want and go to the Conversions tab.
2. Token: check use the channel token to reuse the inbox's own credentials (WhatsApp Cloud already provides the WABA and a usable token). On channels without a WABA, paste the Meta token.
3. Dataset ID: click Detect or create — the platform looks the dataset up from the inbox's WABA, Page or Instagram account and fills the Dataset ID for you (Meta returns the existing dataset or creates one). On channels without a WABA, enter it manually.
4. Test code: enter the test event code (find it in Meta Events Manager, under Test Events).
5. Run a test event: the platform fires synthetic LeadSubmitted and Purchase events straight to Meta with the test code. Confirm they show up under Test Events in Events Manager.
6. Only after the test passes, flip the switch (enabled). From then on, lifecycle events start being sent for real.

The test event bypasses the master switch and the triggers (it exists precisely to validate the wiring before going live). It requires a test event code and valid Meta credentials.

Settings & options

Lifecycle triggers (each one turns an event on/off):

• Events Meta accepts for business messaging: LeadSubmitted, QualifiedLead, ViewContent, AddToCart, InitiateCheckout and Purchase. Meta rejects website-CAPI names (Lead, Contact, Schedule) and custom events such as Lead_Lost in this flow.
• CRM stage → event map (stage_event_map): map a pipeline stage to one of those six supported events to report intermediate milestones beyond won/lost.
• Advanced matching: improves matching by sending extra user signals (always hashed — no raw personal data ever leaves the platform).
• API version: the Meta Marketing API version is set by the platform, the same for every inbox (currently v26.0), and the screen only shows it. Through the API, the meta_api_version field is deprecated: it still accepts only v26.0 or v25.0, but it is ignored when sending.
• Partner agent (meta_partner_agent, default ConversaLabs): identifies your calls to Meta.
• Write-only token: the token is stored and masked — the UI shows only that it exists and the last 4 characters. Saving with the field blank keeps the stored token; there is an explicit action to clear the token when needed.

Messenger and Instagram

• An ad click that opens a conversation in Messenger or Instagram Direct becomes an ad lead with the source Click-to-Messenger or Click-to-Instagram Direct. It shows up in the leads center and triggers the same flows as a WhatsApp lead: the LeadSubmitted event, the automations and Flow Builder flows on the ad lead captured trigger, follow-ups, group distribution and account webhooks.
• WhatsApp-only actions never go out on the wrong channel: a WhatsApp template or flow on a Messenger or Instagram conversation is skipped and logged, and group distribution records a lead without WhatsApp as skipped (no WhatsApp).
• Automations can filter on the ad lead source (Click-to-WhatsApp, lead form, Click-to-Messenger or Click-to-Instagram Direct).
• Meta has no click id on these channels: the event carries the Page and the contact's Page-scoped id (Messenger), or the Instagram account and the contact's Instagram-scoped id. Sales and CRM stages of that conversation count toward the ad within the lead's 7-day window.
• Instagram is measurement only: Meta records the events in Events Manager but doesn't optimize Instagram ads with them today. Purchase optimization applies to ads that click to Messenger and WhatsApp. The Conversions screen shows this notice on Instagram inboxes.

Lead form leads (CRM)

Events for lead-form leads follow Meta's Conversions API for CRM format: they carry the lead ID plus event_source: crm and lead_event_source (the CRM name, the same as the partner agent). Without those fields Meta doesn't use the event for conversion leads optimization.

Ledger & manual triggering

Every send attempt becomes a row in the conversion ledger, with the delivery state:

• pending (processing), sent (delivered to Meta), failed (failed) or skipped (ignored).
• The ledger stores only the hashed / non-PII body that was sent, plus Meta's reply for debugging.
• Each lead has its own ledger — open the lead to see every event sent for it.
• When an attempt fails or is skipped, the ledger says what to do (for example, the permission the token is missing) and keeps Meta's original reason for diagnosis.
• Meta doesn't deduplicate messaging events. The platform retries, with the same identifier, only when it is sure the event didn't arrive: a rate limit, Meta being unavailable, or a connection that never opened. If Meta takes too long to answer after the send, the event is marked failed (may have arrived) and is not resent automatically: check Events Manager before resending.

Manual triggering (admin): from a lead, you can force an event — for example, record a Purchase for a lead that converted outside the CRM. Manual triggering:

• uses a deterministic per-(event, lead) identifier, so re-clicking the same event deduplicates (no double count) but retries if the previous attempt failed;
• accepts only the six business-messaging events listed above; legacy Lead and Contact values sent to the API are normalized to LeadSubmitted and ViewContent;
• requires conversions to be enabled on the lead's inbox.

Reports

The Ads report includes the conversion delivery metrics, side by side with attribution:

• Sent (sent), failed (failed) and skipped (skipped).
• Value delivered to Meta — the sum of the value of delivered events (handy to check what was actually returned as revenue).

skipped events are expected when a deal has no ad attribution: the platform records the event as skipped (visible in the leads center) instead of sending something with no source.

Providers

• Meta Conversions API — active provider (v1). Sends WhatsApp, Messenger and Instagram business-messaging events to the dataset of your WABA, Page or Instagram account, auto-discovering the Dataset ID when it isn't provided. Lead-form leads go out in the CRM format.
• Google Ads and TikTok — exist as prepared scaffolding in provider_settings but do not send events in this version. They stay off by default.

Use cases

• Optimize WhatsApp campaigns on the captured lead and the closed sale, not just the click.
• Return the sale value to Meta to compute ROAS per campaign.
• Manually record a Purchase for a customer who bought through a channel outside the CRM.
• Report intermediate funnel milestones by mapping CRM stages to Meta events.

Tips, limits & best practices

• Always test first: run the test event and confirm it in Events Manager before flipping the switch.
• Idempotency: rely on the deterministic deduplication — won and payment for the same deal collapse into a single delivered Purchase.
• No attribution = skipped: if you see many skipped, check that conversations/leads are really arriving with the ad reference (a healthy CTWA/leadgen capture).
• Token security: never share the token; it is stored encrypted and never displayed.
• Sending never breaks the flow: a delivery failure is recorded in the ledger, it does not interrupt the conversation or the CRM.

Troubleshooting

• conversions_not_enabled: the ads_conversion_tracking flag is off for the account, or the inbox switch is off. Enable the flag and turn on the inbox configuration.
• Dataset not found (no_conversions_dataset): click Detect or create again. The operation is idempotent: it returns the existing dataset or provisions one for the WABA. If it persists, enter the Dataset ID manually. If it still fails, ask the platform administrator to check the Marketing API version, which is set for every inbox.
• Invalid event (invalid_conversion_event): choose one of the six supported business-messaging events. Website events and custom names are not accepted by Meta in this flow.
• no_permission: the token is missing the channel's events permission (whatsapp_business_manage_events, page_events or instagram_manage_events). Reconnect Meta Ads Manager with the permission or paste a token that has it.
• The Page or the contact's id is missing (Messenger/Instagram): the conversation has to come from the Page or Instagram account connected to the inbox.
• Failed with "may have arrived": Meta took too long to answer after the send. Check the event in Events Manager and resend only if it isn't there.
• The test event doesn't appear in Events Manager: confirm the correct test event code and that the token and WABA belong to the same ad account; check under Test Events.
• Events coming out as skipped: the deal has no ad attribution — review the capture (CTWA/leadgen) before sending.

See also

• Ads, CTWA and leadgen with attribution
• Growth & Marketing Studio overview
• Payments overview