Ads conversion tracking (Meta CAPI)

Overview

The platform already captures paid traffic: click-to-WhatsApp ads (CTWA) 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).
• A WhatsApp Cloud inbox with the WhatsApp Business Account (WABA) and a Meta token with Conversions API permission. WhatsApp Web, 360dialog or Twilio inboxes have no WABA — in those cases the Dataset ID and token are entered manually.
• 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 discover automatically — the platform looks the dataset up from the WABA on the Graph API and fills the Dataset ID for you. 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 (meta_api_version, default v25.0) and partner agent (meta_partner_agent, default Conversa Labs): identify 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.

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.

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 business-messaging (WhatsApp) events to your WABA's dataset, auto-discovering the Dataset ID when it isn't provided.
• 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 and check the Graph API version.
• 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 lacks scope/validity for the Conversions API. Generate a token with the right permission and redo the configuration.
• 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