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

| 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**: 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](/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)