Rastreamento de conversões de Ads (Meta CAPI)

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

• 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
• Visão geral do Growth & Marketing Studio
• Visão geral de Pagamentos