Rastrear conversas do WhatsApp vindas de anúncios é ligar três registros: o clique que abriu o contato, a conversa criada e o resultado comercial confirmado depois. Existem duas rotas, e cada uma tem a sua ponte. Num anúncio Click to WhatsApp (CTWA), a ponte é o ctwa_clid, que chega no webhook dentro do objeto referral. Num botão wa.me de landing page, a ponte precisa ser criada antes de o visitante sair do site, guardando fbclid e UTMs sob uma referência curta que viaja na mensagem pronta.
Antes de qualquer código, um aviso que muda o projeto inteiro. Os eventos de mensagens da API de Conversões (action_source: business_messaging) exigem a Cloud API oficial do WhatsApp e permissões de app aprovadas pela Meta. Se a operação usa uma API não oficial, do tipo que conecta um número comum por QR code, você pode até ler o que chega na conversa, mas não consegue mandar esses eventos. Nesse caso, guarde o resultado no CRM e use a rota da landing page, descrita mais abaixo.
Duas rotas, dois identificadores
| Entrada | O que existe antes do WhatsApp | O que chega na conversa | Evento que dá para devolver |
|---|---|---|---|
| Anúncio CTWA | Clique dentro da Meta | referral com source_id e, quando disponível, ctwa_clid |
business_messaging com ctwa_clid |
Landing page com botão wa.me |
fbclid, UTMs e contexto first-party |
O texto que a pessoa enviou | chat com fbc e contato em hash |
| Link orgânico direto | Nada pago | O texto que a pessoa enviou | Nenhum evento de anúncio |
A referência de webhooks de mensagens do WhatsApp lista os campos do referral: source_url, source_id, source_type, headline, body, media_type, image_url ou video_url e thumbnail_url, ctwa_clid e welcome_message. O objeto só vem quando a mensagem foi enviada a partir de um anúncio CTWA. E existe um caso documentado sem o identificador: “The ctwa_clid property is omitted entirely for messages originating from an ad in WhatsApp Status” (conferido em 17/10/2026). Uma conversa vinda de anúncio no Status chega com referral e sem ctwa_clid, e o atendimento não pode depender dele.
O telefone ajuda o atendimento a achar o contato, mas não pode ser a única chave de atribuição. A mesma pessoa volta meses depois por outro anúncio, retoma um chat antigo e compra mais de uma vez. Guarde a identidade do clique e da conversa junto do estado comercial.
Pré-requisitos da API de Conversões para mensagens
A página da Meta sobre a API de Conversões para mensagens (conferida em 17/10/2026) pede:
- Um app de desenvolvedor da Meta com acesso avançado às permissões
whatsapp_business_managementewhatsapp_business_manage_events. Quem já tem acesso avançado awhatsapp_business_messagingdeve ser aprovado automaticamente para a segunda. - O nível de acesso da Marketing API exigido pela página. O limite mudou recentemente: o aviso no topo diz que o requisito de Full Access caiu de 1.500 para 500 chamadas bem-sucedidas da Marketing API nos últimos 15 dias. Confira o número no dia da implementação.
- A Cloud API do WhatsApp. A página ainda cita a On-Premises API, mas informa que a última versão suportada dela expirou em 23/10/2025.
- Integração por Embedded Signup ou Facebook Login for Business.
- Um dataset ligado à conta do WhatsApp Business, criado com
POST /{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset. Se já existir um, a chamada devolve o ID existente.
Guardar o ctwa_clid e devolver pela CAPI
A Meta orienta ler o ctwa_clid no referral do webhook e guardá-lo com a conversa (“Upon receiving the ctwa_clid, store it with the conversation”). O registro mínimo tem ctwa_clid, source_id, ID da conversa, horário de captura e o contato interno do CRM. Trate o valor como dado restrito: retenção definida, acesso limitado, nada de planilha compartilhada.
Quando um resultado acontece, o servidor manda o evento para POST /{DATASET_ID}/events com action_source business_messaging, messaging_channel whatsapp e, em user_data, o whatsapp_business_account_id e o ctwa_clid guardado. Um lead qualificado fica assim:
{
"data": [
{
"event_name": "QualifiedLead",
"event_time": "<unix em segundos do momento da qualificação no CRM>",
"event_id": "crm-qualificacao-<id da conversa>",
"action_source": "business_messaging",
"messaging_channel": "whatsapp",
"user_data": {
"whatsapp_business_account_id": "WABA_ID",
"ctwa_clid": "VALOR_RECEBIDO_NO_WEBHOOK"
}
}
]
}
O event_time é um inteiro com o momento real da qualificação, não o momento do envio. Guarde esse valor e reaproveite nas novas tentativas. A referência de parâmetros do evento de servidor diz que, se algum event_time tiver mais de 7 dias, a Meta devolve erro para a requisição inteira.
O exemplo da própria página da Meta usa a versão v16.0 da Graph API; use a versão atual no dia da implementação. Se o campo ctwa_clid estiver ausente, não gere um valor parecido. Mantenha o resultado no CRM e marque a origem como desconhecida.
Idempotência é responsabilidade sua
A mesma página da Meta avisa: “Meta does not assist with deduplicating events for Conversions API for Business Messaging” e pede que o anunciante deduplique antes de enviar. Um QualifiedLead mandado duas vezes conta duas vezes. Por isso o event_id no exemplo serve ao seu controle de envio, não a uma deduplicação da Meta.
| Evento | Fonte da verdade | Chave contra repetição |
|---|---|---|
LeadSubmitted |
Primeira conversa aceita no atendimento | ID da conversa + LeadSubmitted |
QualifiedLead |
Etapa do CRM com critério escrito | ID da conversa + QualifiedLead, uma vez por conversa |
Purchase |
Pagamento aprovado | ID da transação |
A regra para etapas reabertas: se o lead sai de “qualificado” e volta, a chave da conversa já está no registro de envios e nada sai de novo. Grave a chave antes de enviar e marque como entregue quando a Meta responder. Numa nova tentativa, consulte o registro primeiro.
A página lista também Purchase, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, RatingProvided e ReviewProvided entre os eventos aceitos. Purchase precisa vir do pagamento, com moeda, valor e ID estável da transação. O atendente escrever “fechado” na conversa não é compra.
A rota da landing page
Aqui não existe ctwa_clid. A landing page captura fbclid e UTMs antes do clique no botão, grava os valores num endpoint seu e recebe de volta uma referência curta, aleatória e sem dado pessoal, como W8K4R2M9. A mensagem pronta do wa.me leva essa referência no parâmetro text, codificado para URL. Parâmetros soltos acrescentados ao endereço do wa.me não chegam na conversa.
const numero = '55XXXXXXXXXXX';
const botao = document.querySelector('#botao-whatsapp');
const vistoEm = Date.now(); // ms; vira o creationTime do fbc, só em memória
// Sem consentimento, o botão funciona e não leva referência paga.
botao.href = `https://wa.me/${numero}?text=${encodeURIComponent('Olá, quero saber mais.')}`;
async function criarRegistroDeAtribuicao(dados) {
const resposta = await fetch('/api/atribuicao', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(dados)
});
const { ref } = await resposta.json();
return ref;
}
// Chame só a partir do callback de consentimento aprovado da sua CMP.
async function aoAprovarMarketing() {
const query = new URLSearchParams(location.search);
const ref = await criarRegistroDeAtribuicao({
fbclid: query.get('fbclid'),
fbclid_visto_em: vistoEm,
utm_source: query.get('utm_source'),
utm_medium: query.get('utm_medium'),
utm_campaign: query.get('utm_campaign')
});
const mensagem = encodeURIComponent(`Olá, quero saber mais. Ref ${ref}`);
botao.href = `https://wa.me/${numero}?text=${mensagem}`;
}
A captura e a gravação rodam só depois do consentimento de marketing; o nome do callback muda de uma CMP para outra. Com recusa, o botão continua abrindo o WhatsApp, sem referência paga. Quando a pessoa envia a mensagem, o atendimento ou o webhook extrai a referência e consulta o registro. A conversa fica ligada à visita sem expor o fbclid ao atendente. O padrão é o mesmo do índice first-party que liga landing page e webhook de checkout.
A mensagem pronta pode ser editada ou apagada antes do envio. Registre também o clique no botão e trate a mensagem recebida como prova de que a conversa começou.
Quando o lead qualifica, o evento vai para o dataset do pixel do site com action_source chat, que a referência da Meta define como “Conversion was made via a messaging app, SMS, or online messaging feature”. O website não serve só porque a jornada começou no site: a conversão aconteceu na conversa.
{
"data": [
{
"event_name": "Lead",
"event_time": "<unix em segundos do momento da qualificação no CRM>",
"event_id": "crm-qualificacao-<id da conversa>",
"action_source": "chat",
"user_data": {
"fbc": "fb.1.<fbclid_visto_em em ms>.<fbclid exatamente como chegou>",
"ph": ["<sha256 do telefone só com dígitos e código do país>"]
}
}
]
}
O fbc segue o formato fb.1.<creationTime>.<fbclid> da documentação de fbp e fbc. O creationTime é em milissegundos, do momento em que você viu o fbclid pela primeira vez, e o fbclid vai sem nenhuma mudança de maiúsculas ou minúsculas. Essa rota nunca usa ctwa_clid nem business_messaging. Não renomeie a referência própria como ctwa_clid. A deduplicação entre navegador e servidor do guia da API de Conversões vale aqui se o mesmo lead também for enviado pelo pixel.
Validar antes de usar o relatório
São dois testes diferentes, e misturar os dois gera falsa confiança.
O primeiro é de transporte, feito localmente. Na landing page, abra uma URL com UTMs de teste e um fbclid fictício, clique no botão, envie a mensagem pronta e consulte a referência no armazenamento. Mande o evento com o test_event_code do Gerenciador de Eventos, no dataset do site. IDs fictícios nunca podem chegar a eventos de produção.
O segundo é de ponta a ponta, com um clique real num anúncio. No CTWA, salve o webhook bruto com horário e confira referral, source_id e ctwa_clid. Avance o contato no CRM e confirme que saiu um único evento, ligado ao mesmo registro de conversa. Depois, procure o evento no dataset pelo Gerenciador de Eventos. Uma resposta HTTP aceita prova só que a requisição saiu do seu servidor. E um evento visível no diagnóstico ainda não é crédito de campanha.
- Salve o payload bruto da primeira mensagem, com dados pessoais minimizados.
- Confirme qual rota iniciou a conversa.
- Consulte o registro de atribuição pela chave salva.
- Gere um único avanço comercial e registre qual mudança no CRM autorizou o evento.
- Confira o recibo do envio e o evento no destino.
- Repita a entrega e confirme que o registro de envios segurou a cópia.
- Teste uma conversa orgânica e confirme que ela não ganha origem paga.
Só use o relatório para decidir campanha quando conversa, qualificação e venda fecharem com as fontes operacionais. Se a sua equipe precisa montar essa cadeia ou descobrir onde ela quebrou, veja os serviços da Advanced Tracking Academy para rastreamento e atribuição.