## 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):

| Option | Event sent | Default |
| --- | --- | --- |
| `lead_on_capture` | `LeadSubmitted` when the lead is captured | On |
| `contact_on_first_message` | `ViewContent` on the contact's first message | Off |
| `purchase_on_won` | `Purchase` when the deal is won in the CRM | On |
| `purchase_on_payment` | `Purchase` when a payment is confirmed | On |
| `custom_on_lost` | one supported event selected in `lost_event_name` | Off / no event |

- **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](/hc/ajuda/articles/growth-marketing-ads-ctwa-leadgen-en)
- [Growth & Marketing Studio overview](/hc/ajuda/articles/growth-marketing-overview-en)
- [Payments overview](/hc/ajuda/articles/payments-overview-en)