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.

Dois fluxos de atribuição chegam ao mesmo registro de conversa: um anúncio CTWA traz ctwa_clid pelo webhook, enquanto a landing page leva uma referência no link wa.me.
Os caminhos se encontram no registro da conversa, mas os identificadores continuam separados. Um código criado na landing page nunca deve ser apresentado como ctwa_clid.

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:

  1. Um app de desenvolvedor da Meta com acesso avançado às permissões whatsapp_business_management e whatsapp_business_manage_events. Quem já tem acesso avançado a whatsapp_business_messaging deve ser aprovado automaticamente para a segunda.
  2. 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.
  3. 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.
  4. Integração por Embedded Signup ou Facebook Login for Business.
  5. 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.

  1. Salve o payload bruto da primeira mensagem, com dados pessoais minimizados.
  2. Confirme qual rota iniciou a conversa.
  3. Consulte o registro de atribuição pela chave salva.
  4. Gere um único avanço comercial e registre qual mudança no CRM autorizou o evento.
  5. Confira o recibo do envio e o evento no destino.
  6. Repita a entrega e confirme que o registro de envios segurou a cópia.
  7. 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.