## Visão geral

A plataforma já **captura** o tráfego pago: anúncios click-to-WhatsApp (CTWA) e leads de formulários
de anúncio (leadgen) chegam atribuídos à campanha de origem. O **rastreamento de conversões** é o
outro lado desse ciclo: ele **envia de volta ao Meta** os eventos que acontecem depois — um lead
capturado, o primeiro contato, uma venda fechada — pela **Conversions API (CAPI)**.

Com isso o Meta passa a otimizar as campanhas pelos resultados reais (não só pelo clique) e você mede
**custo por conversão** e **retorno sobre o investimento** com dados de verdade.

Pontos-chave:

- A configuração é **por caixa de entrada** (cada inbox de WhatsApp/anúncios tem seu próprio destino).
- Os eventos são deduplicados por um **identificador determinístico** — a mesma venda nunca é contada
  duas vezes.
- O **token nunca aparece** na interface (somente presença e os 4 últimos caracteres).
- Hoje o provedor ativo é o **Meta Conversions API**; Google Ads e TikTok existem como estrutura
  preparada, mas ainda não enviam eventos.

> A captura (CTWA/leadgen) e a conversão são módulos distintos. Este artigo trata apenas do envio de
> eventos de volta ao Meta. Para a captura e atribuição, veja o artigo de Ads/CTWA/leadgen.

## Pré-requisitos

- Módulo **opt-in**: a sua conta precisa ter a flag `ads_conversion_tracking` habilitada. Ela é
  **diferente** da flag de captura (`growth_ads`) — é possível ter a captura sem o envio de conversões.
- **Permissão de administrador** (toda a configuração e o disparo manual são restritos a admin).
- Uma **caixa de entrada de WhatsApp Cloud** com a **conta de WhatsApp Business (WABA)** e um **token
  do Meta** com permissão para a Conversions API. Caixas de WhatsApp Web, 360dialog ou Twilio não têm
  WABA — nesses casos o **Dataset ID** e o **token** são informados manualmente.
- **Dark-ship**: ao criar, a configuração nasce **desligada** (`enabled` = falso). Nada é enviado até
  você ligar o interruptor — de propósito, para você validar antes.

## Passo a passo

1. Abra **Configurações do Inbox** da caixa de entrada desejada e vá até a aba **Conversões**.
2. **Token**: marque **usar o token do canal** para reaproveitar as credenciais da própria caixa
   (WhatsApp Cloud já traz a WABA e um token utilizável). Em canais sem WABA, cole o token do Meta.
3. **Dataset ID**: clique em **descobrir automaticamente** — a plataforma consulta a WABA no Graph
   e preenche o Dataset ID para você. Em canais sem WABA, informe o Dataset ID manualmente.
4. **Código de teste**: informe o **test event code** (você o encontra no Gerenciador de Eventos do
   Meta, em *Eventos de teste*).
5. **Rode um evento de teste**: a plataforma dispara **LeadSubmitted** e **Purchase** sintéticos direto
   ao Meta, com o código de teste. Confirme que eles aparecem em *Eventos de teste* no Gerenciador.
6. Só **depois** que o teste passar, **ligue o interruptor** (`enabled`). A partir daí os eventos de
   ciclo de vida começam a ser enviados de verdade.

> O evento de teste **ignora** o interruptor principal e os gatilhos (ele serve justamente para validar
> a fiação antes de ligar). Ele exige um **código de teste** e credenciais do Meta válidos.

## Configurações & opções

**Gatilhos de ciclo de vida** (cada um liga/desliga um evento):

| Opção | Evento enviado | Padrão |
| --- | --- | --- |
| `lead_on_capture` | `LeadSubmitted` quando o lead é capturado | Ligado |
| `contact_on_first_message` | `ViewContent` na primeira mensagem do contato | Desligado |
| `purchase_on_won` | `Purchase` quando o negócio é ganho no CRM | Ligado |
| `purchase_on_payment` | `Purchase` quando um pagamento é confirmado | Ligado |
| `custom_on_lost` | um dos eventos aceitos, escolhido em `lost_event_name` | Desligado / nenhum evento |

- **Eventos aceitos pela Meta para mensagens de negócio**: `LeadSubmitted`, `QualifiedLead`,
  `ViewContent`, `AddToCart`, `InitiateCheckout` e `Purchase`. A Meta rejeita os nomes da CAPI de site
  (`Lead`, `Contact`, `Schedule`) e eventos personalizados como `Lead_Lost` nesse fluxo.
- **Mapa de estágio do CRM → evento** (`stage_event_map`): associe um estágio do funil a um dos seis
  eventos aceitos, para reportar marcos intermediários além de ganho/perda.
- **Advanced matching**: melhora a correspondência enviando sinais adicionais do usuário (sempre
  **com hash** — nenhum dado pessoal cru sai da plataforma).
- **Versão da API** (`meta_api_version`, padrão `v25.0`) e **partner agent** (`meta_partner_agent`,
  padrão `Conversa Labs`): identificam suas chamadas no Meta.
- **Token write-only**: o token é **gravado e mascarado** — a interface mostra apenas que existe e os
  4 últimos caracteres. Salvar com o campo em branco **mantém** o token guardado; há uma ação
  explícita para **limpar** o token quando necessário.

## Ledger e disparo manual

Cada tentativa de envio vira **uma linha no ledger de conversões**, com o estado da entrega:

- `pending` (em processamento), `sent` (entregue ao Meta), `failed` (falhou) ou `skipped` (ignorado).
- O ledger guarda apenas o **corpo com hash / sem dados pessoais** que foi enviado, e a **resposta**
  do Meta para depuração.
- Cada lead tem seu **ledger próprio** — você abre o lead e vê todos os eventos enviados por ele.

**Disparo manual** (admin): em um lead, você pode **forçar um evento** — por exemplo, registrar um
`Purchase` de um lead que converteu fora do CRM. O disparo manual:

- usa um identificador determinístico por (evento, lead), então **reclicar o mesmo evento deduplica**
  (não conta duas vezes), mas **tenta de novo** caso a tentativa anterior tenha falhado;
- aceita apenas os seis eventos de mensagens de negócio listados acima; nomes legados `Lead` e `Contact`
  recebidos pela API são convertidos para `LeadSubmitted` e `ViewContent`;
- exige que as **conversões estejam ligadas** na caixa de entrada do lead.

## Relatórios

O relatório de **Ads** traz as métricas de entrega das conversões, lado a lado com a atribuição:

- **Enviados** (`sent`), **falhos** (`failed`) e **ignorados** (`skipped`).
- **Valor reportado** ao Meta — a soma do valor dos eventos entregues (útil para conferir o que foi
  efetivamente devolvido como receita).

Eventos `skipped` são esperados quando um negócio **não tem atribuição de anúncio**: a plataforma
registra o evento como ignorado (visível na central de leads) em vez de enviar algo sem origem.

## Provedores

- **Meta Conversions API** — provedor ativo (v1). Envia eventos de business messaging (WhatsApp) ao
  dataset da sua WABA, descobrindo o Dataset ID automaticamente quando não informado.
- **Google Ads** e **TikTok** — existem como **estrutura preparada** em `provider_settings`, mas
  **não enviam eventos** nesta versão. Permanecem desligados por padrão.

## Casos de uso

- Otimizar campanhas de WhatsApp pelo **lead capturado** e pela **venda fechada**, não só pelo clique.
- Devolver ao Meta o **valor da venda** para calcular ROAS por campanha.
- Registrar manualmente um `Purchase` de um cliente que comprou por um canal externo ao CRM.
- Reportar marcos intermediários do funil mapeando **estágios do CRM** para eventos do Meta.

## Dicas, limites e boas práticas

- **Sempre teste primeiro**: rode o evento de teste e confirme no Gerenciador de Eventos antes de ligar.
- **Idempotência**: confie na deduplicação determinística — ganho e pagamento de um mesmo negócio
  colapsam em um único `Purchase` entregue.
- **Sem atribuição = ignorado**: se você vê muitos `skipped`, verifique se as conversas/leads estão
  realmente chegando com a referência do anúncio (captura CTWA/leadgen saudável).
- **Segurança do token**: nunca compartilhe o token; ele é guardado criptografado e nunca é exibido.
- O envio **nunca derruba o fluxo**: uma falha de entrega é registrada no ledger, não interrompe o
  atendimento nem o CRM.

## Solução de problemas

- **`conversions_not_enabled`**: a flag `ads_conversion_tracking` está desligada para a conta ou o
  interruptor da caixa de entrada está desligado. Habilite a flag e ligue a configuração do inbox.
- **Dataset não encontrado** (`no_conversions_dataset`): clique em **Detectar ou criar** novamente. A
  operação é idempotente: devolve o dataset existente ou provisiona um para a WABA. Se o erro persistir,
  informe o Dataset ID manualmente e verifique a versão da Graph API.
- **Evento inválido** (`invalid_conversion_event`): selecione um dos seis eventos aceitos para mensagens
  de negócio. Eventos de site e nomes personalizados não são aceitos pela Meta nesse fluxo.
- **`no_permission`**: o token não tem escopo/validade para a Conversions API. Gere um token com a
  permissão correta e refaça a configuração.
- **O evento de teste não aparece no Gerenciador**: confirme o **test event code** correto e que o
  token e a WABA pertencem à mesma conta de anúncios; veja em *Eventos de teste*.
- **Eventos saindo como `skipped`**: o negócio não tem atribuição de anúncio — revise a captura
  (CTWA/leadgen) antes do envio.

## Veja também

- [Ads, CTWA e leadgen com atribuição](/hc/ajuda/articles/growth-marketing-ads-ctwa-leadgen-pt-br)
- [Visão geral do Growth & Marketing Studio](/hc/ajuda/articles/growth-marketing-overview-pt-br)
- [Visão geral de Pagamentos](/hc/ajuda/articles/payments-overview-pt-br)