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

Abra Configurações do Inbox da caixa de entrada desejada e vá até a aba Conversões.
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.
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.
Código de teste: informe o test event code (você o encontra no Gerenciador de Eventos do Meta, em Eventos de teste).
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.
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.