Rastrear anúncio do WhatsApp até a venda

Atualizado em 25/10/2026

Para saber qual anúncio de clique para o WhatsApp gerou uma venda, leia o objeto referral que a Cloud API envia no webhook da mensagem recebida: ele traz o ID do anúncio (source_id) e um ID único do clique (ctwa_clid). Guarde esses dados junto do contato e da conversa e, quando a venda acontecer, ligue o pedido a eles. Com isso você calcula vendas por anúncio no seu sistema e ainda pode devolver a venda à Meta pela API de Conversões.

Este guia mostra o payload, o que cada campo significa, como montar a atribuição no banco, como conferir a janela de ponto de entrada gratuito pelo webhook de status e os casos em que o dado não vem.

O que é um anúncio Click-to-WhatsApp

Anúncios de clique para o WhatsApp (Click-to-WhatsApp, ou CTWA) são anúncios do Facebook e do Instagram cujo botão abre uma conversa com a empresa no WhatsApp. A pessoa toca no anúncio, o WhatsApp abre com uma mensagem pronta e, quando ela envia, a sua integração recebe essa mensagem pelo webhook, com os dados do anúncio anexados.

O ponto importante: o Gerenciador de Anúncios mostra quantas conversas o anúncio gerou, mas não sabe o que aconteceu depois. A venda fecha na conversa, no seu CRM ou no seu checkout. Quem liga uma ponta à outra é a sua integração.

O objeto referral no webhook

Segundo a referência do webhook de mensagens de texto, quando a mensagem vem de um anúncio CTWA, ela chega com um objeto referral:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "5511999990000", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "Ana" }, "wa_id": "5511988887777" }],
        "messages": [{
          "from": "5511988887777",
          "id": "wamid.HBgN...",
          "timestamp": "1761400000",
          "type": "text",
          "text": { "body": "Olá! Quero saber mais sobre o plano anual." },
          "referral": {
            "source_url": "https://fb.me/3cr4Wqqkv",
            "source_id": "120226305854810726",
            "source_type": "ad",
            "headline": "Fale com a gente",
            "body": "Plano anual com suporte no WhatsApp",
            "media_type": "image",
            "image_url": "https://scontent.xx.fbcdn.net/...",
            "ctwa_clid": "Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4...",
            "welcome_message": { "text": "Oi! Como podemos ajudar?" }
          }
        }]
      }
    }]
  }]
}

O que cada campo significa

Campo	O que é	Uso na atribuição
`source_id`	ID do anúncio	Chave para agrupar vendas por anúncio
`source_type`	Origem (`ad` para anúncio)	Filtrar o que veio de anúncio
`source_url`	URL do anúncio	Referência para conferir no Facebook
`headline` / `body`	Título e texto principal do anúncio	Identificar o criativo sem consultar a API de Marketing
`media_type`	`image` ou `video`	Comparar formatos
`image_url`, `video_url`, `thumbnail_url`	Mídia do anúncio (conforme o tipo)	Mostrar o criativo no CRM
`ctwa_clid`	ID do clique, único por clique	Enviar a conversão de volta à Meta
`welcome_message.text`	Texto de saudação do anúncio	Contexto para o atendimento

Duas observações da documentação da Meta:

O ctwa_clid não vem quando a mensagem nasce de um anúncio no Status do WhatsApp. Nesse caso, você ainda tem o source_id.
O ctwa_clid é um identificador pessoal, único por clique, segundo o guia da API de Conversões para mensagens comerciais. Trate-o como dado pessoal, com a mesma proteção do telefone do cliente.

Quer testar enquanto lê? Crie sua conta na Vectalk e envie a primeira mensagem pela API oficial. Criar conta grátis →

Como montar a atribuição no seu sistema

A lógica é simples: guardar o clique quando ele chega e ligar a venda ao clique quando ela acontece.

1. Grave o referral assim que a mensagem chegar

Crie uma tabela de origens de conversa:

CREATE TABLE origem_conversa (
  id            BIGSERIAL PRIMARY KEY,
  wa_id         TEXT NOT NULL,
  wamid         TEXT NOT NULL UNIQUE,
  ad_id         TEXT,
  ctwa_clid     TEXT,
  headline      TEXT,
  recebido_em   TIMESTAMPTZ NOT NULL
);

E no handler do webhook:

export function registrarOrigem(value, db) {
  for (const msg of value.messages ?? []) {
    const ref = msg.referral;
    if (!ref || ref.source_type !== 'ad') continue;

    db.inserirOrigem({
      wa_id: msg.from,
      wamid: msg.id,
      ad_id: ref.source_id,
      ctwa_clid: ref.ctwa_clid ?? null, // ausente em anúncios no Status
      headline: ref.headline ?? null,
      recebido_em: new Date(Number(msg.timestamp) * 1000),
    });
  }
}

Use o wamid como chave única: a Meta pode reenviar o mesmo webhook, e o UNIQUE evita duplicar a origem. Para testar com payloads de exemplo antes de rodar anúncio, veja como testar o webhook localmente.

2. Ligue a venda ao último clique

Quando o pedido é criado (no checkout, no CRM ou por um atendente), busque a origem mais recente daquele wa_id dentro de uma janela que você define, por exemplo 7 ou 28 dias:

SELECT ad_id, ctwa_clid
FROM origem_conversa
WHERE wa_id = $1
  AND recebido_em >= now() - interval '7 days'
ORDER BY recebido_em DESC
LIMIT 1;

Grave ad_id e ctwa_clid no pedido. Esse é o seu modelo de último clique. Se uma pessoa clicou em dois anúncios, a venda vai para o mais recente. Escolha a janela conforme o seu ciclo de venda e mantenha a mesma regra ao comparar anúncios.

Se a venda acontece num checkout fora do WhatsApp, inclua um identificador do contato no link enviado na conversa (um código de pedido ou de sessão), para o checkout conseguir voltar ao wa_id.

3. Dê nome aos IDs

O source_id é um número. Para mostrar “Campanha Black Friday – Vídeo 2” no relatório, consulte a API de Marketing com um token que tenha acesso à conta de anúncios:

curl "https://graph.facebook.com/v26.0/120226305854810726?fields=name,adset{name},campaign{name}&access_token=TOKEN_COM_ADS_READ"

Guarde o resultado em cache: o nome do anúncio muda pouco, e consultar a cada mensagem é desperdício.

4. Relatório por anúncio

Com ad_id no pedido, o relatório é uma consulta: conversas por anúncio (da tabela de origens), pedidos e receita por anúncio (da tabela de pedidos) e a taxa de conversão entre os dois. Some o investimento de cada anúncio, exportado do Gerenciador de Anúncios, e você tem custo por venda.

Janela de ponto de entrada gratuito

Conversas que começam por anúncio CTWA têm um benefício de custo. Pela página de preços da Meta, se o usuário escreve a partir de um anúncio CTWA no app Android ou iOS e a empresa responde dentro da janela de atendimento, essa resposta não é cobrada e abre uma janela de ponto de entrada gratuito (FEP). Enquanto ela está aberta, mensagens de marketing, utilidade, autenticação e serviço não são cobradas. Mensagens do Meta Business Agent continuam pagas.

Sobre a duração, há divergência entre fontes oficiais: a documentação para desenvolvedores diz que a janela pode ficar aberta por até 7 dias, e o site comercial do WhatsApp Business ainda fala em 72 horas. Em vez de depender de um número fixo, confira no webhook de status. Segundo a referência de status, mensagens enviadas dentro da janela gratuita vêm com pricing.type igual a free_entry_point. A mesma referência lista a categoria referral_conversion para conversas de ponto de entrada gratuito:

{
  "id": "wamid.HBgN...",
  "status": "delivered",
  "recipient_id": "5511988887777",
  "pricing": {
    "pricing_model": "PMP",
    "type": "free_entry_point",
    "category": "referral_conversion"
  }
}

Registrar o pricing de cada envio permite somar ao relatório quanto você economizou em mensagens por anúncio. Veja o webhook de status de mensagem e o artigo sobre preço da API do WhatsApp no Brasil.

Duas consequências práticas:

Responda rápido. A janela gratuita só abre se a empresa responder dentro da janela de atendimento. Uma mensagem de boas-vindas automática resolve.
Concentre o follow-up. Lembretes e ofertas enviados dentro da janela gratuita não pagam a tarifa de marketing. É um bom momento para a recuperação de PIX e carrinho.

Quando o referral não vem

Situação	O que acontece	O que fazer
Anúncio exibido no Status do WhatsApp	Vem `referral`, mas sem `ctwa_clid`	Atribua pelo `source_id`
Cliente salva o número e escreve dias depois, fora do anúncio	Mensagem comum, sem referral	A conversa conta como orgânica no seu sistema
Webhook fora do ar quando a mensagem chegou	O dado se perde se você não processar o reenvio	Responda 200 rápido e processe em fila
Uso pelo app de computador ou web	A janela gratuita não se aplica (a página de preços cita só Android e iOS)	Não conte com a gratuidade para esses casos

Do relatório à otimização: API de Conversões

Saber qual anúncio vende é metade do caminho. A outra metade é contar isso para a Meta, para que a entrega dos anúncios aprenda com vendas e não só com conversas iniciadas. Isso é feito enviando eventos (como Purchase) com o ctwa_clid para a API de Conversões. O passo a passo está em API de Conversões da Meta para WhatsApp.

Como fazer com a Vectalk

A Vectalk repassa os webhooks no formato da Meta, então o objeto referral chega na sua URL do jeito descrito acima, sem conversão. Para começar:

Conecte o número em apps.vectalk.com.br/register.
Registre o webhook com POST /api/webhooks (documentação). Dá para registrar mais de uma URL por instância, por exemplo uma para o atendimento e outra só para o serviço de atribuição.
Grave referral e pricing como mostrado neste artigo.

Para os fundamentos de webhook e da API, veja webhook da API do WhatsApp e o guia da API oficial do WhatsApp.

Perguntas frequentes

O referral vem em todas as mensagens da conversa?

A documentação da Meta descreve o referral na mensagem enviada pelo usuário a partir do anúncio. Grave-o assim que chegar e não dependa de recebê-lo de novo nas mensagens seguintes.

Qual a diferença entre source_id e ctwa_clid?

O source_id é o ID do anúncio: igual para todos que clicaram nele. O ctwa_clid é o ID de um clique específico, de uma pessoa. Para relatório por anúncio, use o source_id; para devolver a conversão à Meta, use o ctwa_clid.

Consigo saber a campanha e o conjunto de anúncios?

Sim, consultando o ID do anúncio na API de Marketing com um token que tenha acesso à conta de anúncios. O webhook do WhatsApp traz só o ID do anúncio e os textos do criativo.

A janela gratuita é de 72 horas ou 7 dias?

A documentação para desenvolvedores da Meta fala em até 7 dias; o site comercial do WhatsApp Business ainda fala em 72 horas. Confira mensagem a mensagem pelo pricing.type no webhook de status: free_entry_point indica que a mensagem não foi cobrada por estar na janela.

Funciona com anúncio do Instagram?

Sim. Anúncios de clique para o WhatsApp podem rodar no Facebook e no Instagram, e a mensagem chega ao WhatsApp com o referral do mesmo jeito.

Fontes oficiais consultadas em 25/10/2026: Webhook de mensagens de texto (referral), Webhook de status (pricing), Preços da plataforma, Tabela de preços no site do WhatsApp Business, API de Conversões para mensagens comerciais, Sequências de boas-vindas para CTWA, Vectalk: webhooks.

Coloque o WhatsApp oficial da sua empresa para funcionar

Crie sua conta, conecte seu número à API oficial (dá para manter o app com coexistência) e comece a atender e enviar mensagens.

Criar conta grátis

Ler a documentação

Anúncios Click-to-WhatsApp: como saber qual anúncio gerou a venda