TL;DR: A Whapi.Cloud inclui ctwa_clid em cada webhook de Click-to-WhatsApp em context.ad.ctwa, sem nenhuma configuração da sua parte. Leia o valor, salve no seu CRM e faça um POST para a API de Conversões da Meta como user_data.ctwa_clid para tornar seu investimento em anúncios do WhatsApp rastreável. Se context.ad estiver ausente, a mensagem é orgânica: pule o reporte para a CAPI nesse evento. Use Lead como nome de evento padrão.
O que São os Anúncios Click-to-WhatsApp?
Os anúncios Click-to-WhatsApp (CTWA) são formatos de anúncios da Meta no Facebook e no Instagram. Ao tocar no call-to-action, uma conversa do WhatsApp é aberta diretamente, sem página de destino intermediária nem formulário para preencher.
O usuário toca no anúncio, o WhatsApp abre e a primeira mensagem chega diretamente à sua caixa de entrada. Uma vez dentro do WhatsApp, um pixel de navegador padrão não consegue acompanhá-lo. Antes que o ctwa_clid existisse, todo o gasto com anúncios do WhatsApp era praticamente inrastreável: um lead que clicou no seu anúncio era indistinguível de um que digitou seu número manualmente.
O que É ctwa_clid e Como Funciona?
Quando um usuário toca em um anúncio Click-to-WhatsApp, a Meta injeta um identificador de clique chamado ctwa_clid na conversa.
Ele percorre a primeira mensagem recebida e permite que você vincule o lead do WhatsApp ao anúncio exato, à campanha e ao segmento de público que o geraram.
Diferentemente de um click ID de UTM, o ctwa_clid vive nos metadados da mensagem, não em um parâmetro de query string de URL. A Meta o gera no momento do toque no anúncio e o anexa ao objeto de referral da primeira mensagem recebida.
A Whapi.Cloud entrega o ctwa_clid nativamente em cada webhook recebido qualificado em context.ad.ctwa. Zero configuração da sua parte: sem flags especiais, sem chamadas de API adicionais. Alguns provedores removem ou omitem o objeto de referral antes que o payload chegue ao seu handler. A Whapi.Cloud repassa o objeto de atribuição completo por padrão.
Três campos de atribuição chegam juntos no mesmo evento de webhook:
-
context.ad.ctwa: o próprio valor do
ctwa_clid. Este é o identificador que você envia para a API de Conversões da Meta comouser_data.ctwa_clidpara reportar a conversão offline. -
context.conversion.data: o token de deduplicação. Passe-o como
event_idno seu payload da CAPI. Se sua configuração também acionar um pixel de navegador para a mesma sessão, a Meta usa esse token para deduplicar os eventos server-side e client-side, de modo que a conversão seja contada uma vez, não duas. -
context.ad.source.id identifica o criativo do anúncio específico. Combine-o com o
ctwa_clidquando precisar de atribuição ao nível do criativo: não apenas "esse lead veio da campanha X", mas "esse lead veio da variante de carrossel com aquele título e imagem específicos".
Pré-requisitos: Três Coisas para Verificar antes de Ver o ctwa_clid
As três condições precisam ser verdadeiras antes que o ctwa_clid apareça nos seus webhooks. Se qualquer uma estiver faltando, context.ad não estará presente, independentemente de como seu handler de webhook estiver escrito.
- Uma campanha Click-to-WhatsApp ativa. A mensagem recebida deve originar-se de um toque em um anúncio de CTWA. Contatos orgânicos (usuários que encontram seu número via busca, link compartilhado ou entrada direta) enviam mensagens sem dados de referral anexados.
- Atribuição habilitada nas configurações do WhatsApp Business. Este é o passo que a maioria das equipes deixa passar. Abra as configurações da sua conta do WhatsApp Business, encontre a seção de Atribuição de Anúncios e habilite-a. Sem essa opção, a Meta não inclui o objeto de referral na conversa, e
context.adnunca aparece no payload do webhook. - Um endpoint de webhook da Whapi.Cloud configurado. A URL do seu backend deve estar registrada no painel da Whapi.Cloud e precisa ser acessível publicamente. A configuração padrão de webhook se aplica: nenhum modo de atribuição especial ou permissão extra é necessário no lado da Whapi.Cloud.
O Webhook da Whapi.Cloud: Onde Fica o ctwa_clid
Quando uma mensagem com atribuição de CTWA chega, a Whapi.Cloud entrega um payload de webhook que inclui um objeto context junto com os campos padrão da mensagem. Esse objeto tem duas sub-chaves: ad (dados da fonte do clique) e conversion (token de deduplicação).
Abaixo está o payload completo do webhook da Whapi.Cloud para uma mensagem de Click-to-WhatsApp com atribuição. Estude o bloco context: tudo o que é necessário para o reporte na CAPI está lá.
{
"messages": [
{
"id": "msg_id_123",
"from_me": false,
"type": "text",
"chat_id": "[email protected]",
"timestamp": 1714000000,
"source": "mobile",
"text": {
"body": "Hi, I saw your ad and I'm interested"
},
"context": {
"conversion": {
"data": "CONVERSION_TOKEN_ABC123",
"source": "FB_Ads"
},
"ad": {
"title": "Summer Sale — 50% Off",
"body": "Limited time offer. Click to chat now.",
"media_type": "image",
"preview_url": "https://example.com/ad-preview.jpg",
"source": {
"id": "AD_ID_987654321",
"type": "ad",
"url": "https://fb.me/adlink123"
},
"attrib": true,
"ctwa": "CTWA_CLICK_ID_1234567890"
}
},
"from": "60123456789",
"from_name": "John Doe"
}
]
}Os dois caminhos para memorizar: messages[0].context.ad.ctwa é o ctwa_clid. messages[0].context.conversion.data é o token de deduplicação. Ambos são necessários para um payload completo da CAPI.
context.ad.source.id também viaja no mesmo webhook: esse é o ID do criativo do anúncio. Um único evento de webhook entrega tanto a atribuição ao nível do usuário (ctwa_clid) quanto a atribuição ao nível do criativo (ID do anúncio) simultaneamente. Nenhuma segunda chamada de API é necessária para descobrir qual criativo o usuário viu.
Para a referência completa de campos e exemplos de casos extremos, consulte o artigo da base de conhecimento da Whapi.Cloud sobre rastreamento de leads do WhatsApp a partir de anúncios da Meta. A especificação completa do payload de webhook recebido, incluindo todos os campos de context, está na referência do formato de webhooks recebidos.
Passo a Passo: Extraia o ctwa_clid e Envie para a API de Conversões da Meta
Seis passos desde o recebimento do webhook até uma conversão offline reportável no Gerenciador de Anúncios da Meta. Os passos 1–3 ficam no seu handler de webhook; os passos 4–6 são o POST da CAPI.
Passo 1: Confirme o recebimento imediatamente, depois processe. Seu endpoint de webhook deve retornar um 200 antes de qualquer trabalho assíncrono. A Whapi.Cloud tenta reenviar webhooks que expiram, o que cria processamento duplicado. Responda primeiro, depois lide com a lógica de atribuição.
Passos 2–3: Extraia e armazene. Leia context.ad.ctwa do payload. Se estiver ausente, a mensagem é orgânica: saia cedo e pule a CAPI. Se estiver presente, salve-o junto ao registro de contato no seu CRM antes de fazer qualquer outra coisa. A CAPI pode ser chamada de forma assíncrona; seu registro de CRM deve ser criado de forma síncrona para que nenhum lead seja perdido se a chamada à CAPI falhar.
// Node.js / Express — webhook handler
app.post('/webhook', async (req, res) => {
res.sendStatus(200); // Step 1: acknowledge before processing
const messages = req.body.messages || [];
for (const msg of messages) {
if (msg.from_me) continue; // skip outbound messages
const ctwaClid = msg.context?.ad?.ctwa; // Step 2: ctwa_clid
const convToken = msg.context?.conversion?.data; // deduplication token
const adId = msg.context?.ad?.source?.id; // creative-level attribution
if (!ctwaClid) continue; // organic message — no CAPI event
// Step 3: persist lead in CRM before calling CAPI
await crm.createLead({
phone: msg.from,
name: msg.from_name,
ctwa_clid: ctwaClid,
ad_id: adId,
source: 'whatsapp_ctwa',
});
// Steps 4–6: report offline conversion to Meta CAPI
await sendToMetaCAPI({ ctwaClid, convToken, phone: msg.from });
}
});Passos 4–6: Monte e faça POST do evento da CAPI. O endpoint da API de Conversões da Meta é https://graph.facebook.com/v19.0/{PIXEL_ID}/events. Use Lead como nome do evento para fluxos de CTWA equivalentes a envios de formulário: este é o sinal de otimização correto para o algoritmo da Meta. Passe ctwa_clid como user_data.ctwa_clid e context.conversion.data como event_id.
// Steps 4–6: Meta Conversions API POST
async function sendToMetaCAPI({ ctwaClid, convToken, phone }) {
const pixelId = process.env.META_PIXEL_ID;
const accessToken = process.env.META_CAPI_TOKEN;
const payload = {
data: [
{
event_name: 'Lead', // use 'Lead' for CTWA qualification flows
event_time: Math.floor(Date.now() / 1000),
event_id: convToken, // dedup token from context.conversion.data
action_source: 'business_messaging',
user_data: {
ctwa_clid: ctwaClid, // ctwa_clid from context.ad.ctwa
ph: hashSHA256(phone), // hashed phone (SHA-256, no leading +)
},
},
],
};
const url = `https://graph.facebook.com/v19.0/${pixelId}/events?access_token=${accessToken}`;
const resp = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
return resp.json();
}Assim que a Meta recebe o evento, a conversão aparece no Gerenciador de Anúncios como um evento offline atribuído. Isso alimenta diretamente o ROAS reportado da sua campanha. A janela de atribuição segue as configurações da sua conta Meta (padrão: 7 dias por clique, 1 dia por visualização).
Três detalhes de implementação que evitam erros de reporte:
-
Faça hash do número de telefone. A Meta exige que campos de PII transmitidos à CAPI sejam hasheados com SHA-256. Remova o sinal "+" inicial antes do hash; não o inclua na string bruta.
-
event_id é obrigatório se você usa um pixel de navegador. Quando tanto a CAPI server-side quanto um pixel de navegador são acionados para a mesma conversão, a Meta deduplica usando
event_id. Omita esse campo e o mesmo lead pode ser contado duas vezes nos seus relatórios, inflando as conversões e corrompendo os sinais de otimização da campanha. -
Não use
Purchasea menos que uma transação seja confirmada. UseLeadpara a qualificação do primeiro contato. ReservePurchasepara fluxos onde um pagamento é coletado dentro da conversa do WhatsApp. Nomes de eventos incorretos enviam sinais errados ao algoritmo de lances da Meta, que otimiza para o resultado errado nos ciclos subsequentes da campanha.
Casos de Uso Práticos para Atribuição com ctwa_clid
Três cenários onde a atribuição com ctwa_clid muda diretamente a forma como os orçamentos de marketing são alocados.
| Caso de Uso | Campo que Você Extrai | Resultado de Negócio |
|---|---|---|
| Rastreamento de origem de leads no CRM | context.ad.ctwa armazenado com o registro de contato na criação |
A equipe de vendas vê qual campanha gerou cada lead; o marketing obtém dados de ROAS de ciclo fechado sem um sistema de tagging manual |
| Otimização ao nível do criativo | context.ad.source.id mapeado para a taxa de conversão de conversa em venda |
Identifique quais criativos geram conversas qualificadas versus as de alto volume mas não qualificadas; mova o orçamento para as variantes que produzem receita |
| Reporte de conversões offline para a Meta | ctwa_clid enviado para a CAPI como evento Lead |
O algoritmo de otimização da Meta recebe sinais de conversão reais do downstream do WhatsApp, o que melhora a qualidade do público-alvo nos ciclos subsequentes da campanha |
E se context.ad Estiver Ausente do Webhook?
Nem toda mensagem recebida vem de um anúncio. Contatos orgânicos encontram seu número por indicação boca a boca, links compartilhados, QR codes ou busca direta, e suas mensagens não trazem dados de referral.
Na Whapi.Cloud, isso é simples de detectar: se context.ad estiver ausente do payload, não existe atribuição de anúncio. Faça a verificação antes de qualquer lógica da CAPI:
// Attribution guard — always run this check first
const ctwaClid = msg.context?.ad?.ctwa;
if (!ctwaClid) {
// Organic contact — create CRM record normally, skip CAPI
return;
}
// Attribution confirmed — proceed with CAPI reporting
Enviar um evento para a CAPI sem um ctwa_clid válido cria ruído de atribuição no Gerenciador de Anúncios da Meta e infla as contagens de conversões reportadas. Contatos orgânicos são valiosos — eles simplesmente não carregam atribuição de anúncio, o que é a representação precisa de como chegaram.
A Whapi.Cloud expõe a cadeia completa de atribuição de Click-to-WhatsApp — ctwa_clid, token de deduplicação e ID do criativo do anúncio — em cada webhook qualificado, por padrão. ctwa_clid mais Meta CAPI equivale a ROAS comprovável e reportável para equipes de vendas que operam pelo WhatsApp. Se seu provedor atual de API do WhatsApp não expõe esses dados, cada real gasto em anúncios de CTWA é uma caixa-preta sem retorno mensurável.
