Conectar o CRM à API de Conversões da Meta: o que enviar, quando e com qual identificador

O Pixel da Meta registra o que acontece no navegador. A venda, em muitos negócios, acontece fora dele: numa conversa de WhatsApp, numa reunião, num contrato assinado. A API de Conversões existe para fechar essa lacuna, e o CRM é a fonte natural dos eventos, porque é onde cada etapa fica registrada.

O guia está organizado por cenário, porque a Meta documenta caminhos diferentes para lead de formulário, para site e para anúncio que abre o WhatsApp, cada um com seus identificadores e requisitos. Para trazer o lead do formulário até o CRM, veja antes leads do Facebook Ads no CRM; o retorno equivalente para o Google está em leads do Google Ads no CRM. Documentação conferida em 31 de outubro de 2026.

Qual cenário da API de Conversões se aplica ao seu caso?

Depende de onde nasce o lead. Formulário instantâneo, site com Pixel e anúncio que abre o WhatsApp usam identificadores diferentes e pedem eventos diferentes. Escolher o cenário errado é o motivo mais comum de a integração rodar sem melhorar a campanha.

O que a Meta exige para o Conversion Leads funcionar?

O Conversion Leads é a meta de desempenho que otimiza o anúncio por qualidade do lead, e a documentação da Meta o limita aos formulários instantâneos. Ele funciona quando o CRM devolve as etapas do lead e o volume é suficiente para a Meta aprender.

• Usar Lead Ads (formulários instantâneos) do Facebook ou do Instagram.
• Guardar no CRM o Lead ID de 15 a 17 dígitos e enviá-lo com cada evento. Sem ele, enviar parâmetros do cliente, como telefone ou e-mail.
• Gerar ao menos 200 leads por mês.
• Enviar os dados pelo menos uma vez por dia.
• A etapa que você quer otimizar deve acontecer em até 28 dias depois da geração do lead.
• Essa etapa deve ocorrer em uma faixa de 1 a 40 em cada 100 leads; fora disso, a Meta tem pouco sinal para aprender.

A Meta estima cerca de 3 a 4 semanas até o ganho aparecer, somando a verificação dos dados e o período de aprendizado. Quem anuncia com pouco volume por mês não deve forçar essa integração: ainda vale gravar a origem e medir no BI, como em rastrear a origem do lead. A conta de quanto cada canal vendeu está em como medir vendas do tráfego pago.

Como transformar as etapas do funil em eventos?

Escolha duas ou três etapas que indiquem qualidade, nunca todas. Cada uma vira um evento com nome fixo. O erro mais comum é mandar dez eventos; a Meta aprende melhor com poucos sinais que realmente separam o lead bom do ruim.

Que campos o evento precisa levar?

Pela referência da Meta, todo evento do servidor leva nome do evento, horário, origem da ação e dados do cliente. O horário é um carimbo Unix em segundos, e a Meta aceita evento de até 7 dias atrás; se um evento do lote passar disso, a requisição inteira falha.

• event_name: nome padrão ou personalizado do evento.
• event_time: quando o evento aconteceu, em segundos Unix, no máximo 7 dias antes do envio.
• action_source: de onde veio a ação. Os valores aceitos incluem site, e-mail, chat, sistema gerado e mensagens de negócio.
• user_data: dados do cliente. E-mail e telefone exigem hash SHA-256 depois de normalizados (e-mail em minúsculas e sem espaços; telefone só com números, incluindo o código do país). O Lead ID, os cookies fbc e fbp e o endereço IP não levam hash.
• event_id: recomendado para evitar contagem em dobro quando o mesmo evento vem do Pixel e do servidor.

Como evitar que o mesmo evento seja contado duas vezes?

Enviando o mesmo nome de evento e o mesmo event_id pelo Pixel e pela API. A Meta descarta o segundo evento que chegar em até 48 horas depois do primeiro. Sem esse casamento, a conversão de site aparece em dobro e a campanha aprende com número inflado.

A regra vale para eventos que existem nas duas pontas, como uma compra no site. Eventos que só existem no CRM, como uma proposta enviada, não têm par no navegador e seguem apenas pelo servidor. A deduplicação, aliás, não atua quando só uma das origens envia o evento.

E quando o lead chega por um anúncio que abre o WhatsApp?

Nesse caso a Meta tem uma versão própria, para mensagens de negócio. O identificador é o ctwa_clid, que chega na mensagem recebida, e o evento só deve representar algo que aconteceu na conversa. O desenho do anúncio e da leitura da campanha está em anúncio de clique para o WhatsApp.

• O ctwa_clid vem do objeto de referência no aviso de mensagem da plataforma do WhatsApp; o CRM guarda esse valor junto com a conversa.
• O envio usa action_source de mensagens de negócio e canal WhatsApp, com a conta de WhatsApp Business no pedido.
• A documentação exige um app de desenvolvedor, permissões avançadas de gestão do WhatsApp e de eventos, e uma integração com a plataforma do WhatsApp. Por isso a AD PRO costuma montar esse caso junto com a estrutura da API oficial do WhatsApp.

Como a AD PRO monta isso com o DataCrazy?

Na implementação, a AD PRO, parceira Premier e implementadora do DataCrazy, liga o CRM a um fluxo no n8n: quando o lead chega a uma etapa-chave, o fluxo monta o evento com o identificador e os dados do contato, aplica o hash, envia à Meta e registra a resposta. O desenho exato depende do plano do DataCrazy e dos webhooks disponíveis.

1. 1
   Grave o identificador na entrada

   O Lead ID, o ctwa_clid ou o clique do site entram em campo próprio do contato, no momento da criação, e nunca são editados.

2. 2
   Escolha as duas ou três etapas-sinal

   Converse com a equipe comercial sobre qual etapa separa o lead bom do ruim. Use a etapa de venda com valor quando existir.

3. 3
   Monte o fluxo de envio

   Webhook da mudança de etapa, normalização, hash, chamada à API de Conversões, registro do resultado. Veja integração do DataCrazy com o n8n.

4. 4
   Verifique no Gerenciador de Eventos

   Confirme que os eventos aparecem, com os campos corretos e sem duplicidade, antes de mudar a meta da campanha.

5. 5
   Compare com o BI

   O número de vendas por campanha no BI do DataCrazy precisa bater com o que a Meta recebeu. Se divergir, o problema está no envio.

Cenário: [ ] formulário instantâneo  [ ] site com Pixel  [ ] anúncio que abre o WhatsApp
Identificador gravado no lead: [ ] Lead ID  [ ] ctwa_clid  [ ] fbc/fbp

Etapa do CRM | Evento enviado | Valor (sim/não) | Quem decide a etapa
------------ | ------------- | ---------------- | -------------------
[etapa 1]    | [nome do evento] | [ ]            | [responsável]
[etapa 2]    | [nome do evento] | [ ]            | [responsável]
[venda]      | Compra           | [ ] sim        | [responsável]

Conferências antes de ligar:
[ ] E-mail em minúsculas e telefone só com números e código do país, ambos com hash
[ ] Lead ID, fbc, fbp e IP sem hash
[ ] event_time com no máximo 7 dias
[ ] Mesmo event_id no Pixel e no servidor, quando o evento existe nos dois
[ ] Envio pelo menos uma vez por dia
[ ] Eventos apareceram no Gerenciador de Eventos sem duplicidade