## Visão geral

A plataforma já **captura** o tráfego pago: anúncios click-to-WhatsApp (CTWA), anúncios que abrem uma
conversa no **Messenger** (click-to-Messenger) ou no **Instagram Direct** (click-to-Instagram Direct) 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 um canal da Meta e um **token** com a permissão de eventos desse canal:
  - **WhatsApp Cloud**: a **conta de WhatsApp Business (WABA)** e `whatsapp_business_manage_events`;
  - **Messenger** (caixa da Página do Facebook): a **Página** e `page_events`;
  - **Instagram**: a **conta profissional do Instagram** e `instagram_manage_events`.

  Caixas de WhatsApp Web, 360dialog ou Twilio não têm WABA — nesses casos o **Dataset ID** e o **token**
  são informados manualmente.
- O login da Página e o do Instagram **não pedem** `page_events` nem `instagram_manage_events`. Para o
  Messenger e o Instagram, use o token da conexão com o **Gerenciador de Anúncios da Meta** (as permissões
  vêm da configuração do Login do Facebook para Empresas no Painel de Apps da Meta) ou cole um token que
  tenha a permissão.
- **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 **Detectar ou criar** — a plataforma consulta a WABA, a Página ou a conta do
   Instagram da caixa e preenche o Dataset ID para você (a Meta devolve o dataset existente ou cria um).
   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**: a versão da API de Marketing da Meta é definida pela plataforma, a mesma para todas as
  caixas (hoje `v26.0`), e a tela só a mostra. Pela API, o campo `meta_api_version` ficou obsoleto: ainda
  aceita apenas `v26.0` ou `v25.0`, mas é ignorado no envio.
- **Partner agent** (`meta_partner_agent`, padrão `ConversaLabs`): identifica 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.

### Messenger e Instagram

- Um clique em anúncio que abre uma conversa no Messenger ou no Instagram Direct vira um **lead de
  anúncio** com a origem **Click-to-Messenger** ou **Click-to-Instagram Direct**. Ele aparece na central de
  leads e dispara os mesmos fluxos de um lead do WhatsApp: o evento `LeadSubmitted`, as automações e o
  Flow Builder do gatilho *lead de anúncio capturado*, os follow-ups, a distribuição de grupos e os webhooks
  da conta.
- Ações que só existem no WhatsApp **não saem pelo canal errado**: um template ou flow do WhatsApp numa
  conversa do Messenger ou do Instagram é ignorado e registrado, e a distribuição de grupos registra o
  lead sem WhatsApp como *ignorado (sem WhatsApp)*.
- As automações podem filtrar pela **origem do lead de anúncio** (Click-to-WhatsApp, formulário,
  Click-to-Messenger ou Click-to-Instagram Direct).
- A Meta não tem clique identificado nesses canais: o evento leva a Página e o ID do contato na Página
  (Messenger), ou a conta do Instagram e o ID do contato no Instagram. Vendas e estágios do CRM dessa
  conversa contam como do anúncio, na janela de 7 dias do lead.
- **Instagram é só mensuração**: a Meta registra os eventos no Gerenciador de Eventos, mas hoje não
  otimiza anúncios do Instagram com eles. A otimização por compra vale para anúncios que levam ao Messenger
  e ao WhatsApp. A tela de Conversões mostra esse aviso nas caixas do Instagram.

### Leads de formulário (CRM)

Os eventos de leads de formulário de anúncio seguem o formato da **API de Conversões para CRM** da Meta:
levam o ID do lead e os campos `event_source: crm` e `lead_event_source` (o nome do CRM, o mesmo do
*partner agent*). Sem esses campos a Meta não usa o evento na otimização por leads de conversão.

### 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.
- Quando uma tentativa falha ou é ignorada, o ledger mostra **o que fazer** (por exemplo, a permissão que
  falta no token) e mantém o motivo original da Meta para diagnóstico.
- **A Meta não deduplica eventos de mensagens.** A plataforma tenta de novo, com o mesmo identificador,
  só quando tem certeza de que o evento não chegou: limite de chamadas, Meta indisponível ou conexão
  que nem chegou a abrir. Se a Meta demorar a responder depois do envio, o evento fica como falho
  (*pode ter chegado*) e **não** é reenviado sozinho: confira no Gerenciador de Eventos antes de reenviar.

**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 do WhatsApp, do
  Messenger e do Instagram ao dataset da WABA, da Página ou da conta do Instagram, descobrindo o Dataset
  ID automaticamente quando não informado. Leads de formulário saem no formato de CRM.
- **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. Se ainda falhar, peça ao administrador da plataforma para conferir a
  versão da API de Marketing, que é definida para todas as caixas.
- **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 a permissão de eventos do canal (`whatsapp_business_manage_events`,
  `page_events` ou `instagram_manage_events`). Reconecte o Gerenciador de Anúncios da Meta com a permissão
  ou cole um token que a tenha.
- **Faltou a Página ou o ID do contato** (Messenger/Instagram): a conversa precisa ter vindo da Página ou
  da conta do Instagram conectada à caixa.
- **Falhou com "pode ter chegado"**: a Meta demorou a responder depois do envio. Confira o evento no
  Gerenciador de Eventos e só reenvie se ele não estiver lá.
- **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)