Saiba Qual Anúncio Iniciou Cada Conversa no WhatsApp
Quando alguém toca no seu anúncio Click-to-WhatsApp ou publicação impulsionada, a primeira mensagem traz o anúncio junto. O StartMessaging salva essa informação no novo contato, mostra no CRM e envia aos seus sistemas por webhook, para que nenhum lead de anúncio chegue anônimo.
✦ Teste grátis de 14 dias · Seu próprio número do WhatsApp Business · A Meta cobra as mensagens diretamente
O Anúncio Chega Junto com a Primeira Mensagem
Você cria e paga os anúncios no Gerenciador de Anúncios da Meta. Quando um cliente toca em um deles e envia a primeira mensagem, o WhatsApp anexa uma referência: o tipo de origem, o ID do anúncio ou da publicação, o link, o título, o texto do anúncio e um ID de clique (ctwaClid). O StartMessaging lê essa referência assim que a mensagem chega à sua caixa de entrada compartilhada.
- Funciona com anúncios Click-to-WhatsApp e publicações impulsionadas
- Título, texto, ID e link do anúncio ou publicação capturados
- ID de clique (ctwaClid) guardado para seus relatórios de conversão
- Um selo “A janela grátis do anúncio termina…” enquanto a janela grátis de 72 horas da Meta está aberta
Cada Lead de Anúncio Chega ao CRM com Seu Anúncio
Um contato criado por um clique em anúncio recebe a origem "Anúncio Click-to-WhatsApp" e o anúncio como campos personalizados: ctwa_source_type, ctwa_source_id, ctwa_source_url, ctwa_headline, ctwa_body e ctwa_clid. Abra o contato e um cartão "De um anúncio Click-to-WhatsApp" mostra o anúncio tocado. Os campos são definidos uma única vez, por essa primeira mensagem. Um contato que você já tinha mantém a origem e os campos originais, e a referência ainda chega no webhook message.received.
- Origem do lead registrada como "Anúncio Click-to-WhatsApp"
- Dados do anúncio salvos como campos personalizados, definidos uma vez
- Exibido na página do contato junto às tags e notas
Do Toque no Anúncio ao Lead Qualificado
1. Veicule o anúncio no Gerenciador de Anúncios da Meta
Crie um anúncio Click-to-WhatsApp, ou impulsione uma publicação com botão do WhatsApp, que abra uma conversa com o número conectado ao StartMessaging.
2. O cliente toca e escreve
A primeira mensagem chega à caixa de entrada compartilhada da equipe com a referência do anúncio anexada.
3. O contato é criado com o anúncio
Um novo contato recebe a origem ctwa_ad e os campos personalizados ctwa_*. Seus sistemas recebem a referência em message.received e a origem em contact.created.
4. Encaminhe o lead
Um fluxo de chatbot com o gatilho de primeira mensagem recebe cada nova conversa, incluindo cliques em anúncios: faça perguntas de qualificação, adicione uma tag, mova o contato para uma etapa do funil e atribua um agente.
5. Informe a conversão você mesmo
Quando o lead compra, o seu próprio sistema envia o ctwaClid salvo para a API de Conversões da Meta; o StartMessaging não envia conversões à Meta por você. Para creditar a venda a uma campanha do StartMessaging, informe-a com POST /api/v1/conversions no plano Business.
Uma Referência, Três Lugares para Usá-la
Qualquer campo da referência pode vir vazio quando a Meta não o envia.
| Dados do anúncio | No contato (CRM) | Webhook message.received | API REST |
|---|---|---|---|
| Tipo de origem, ID do anúncio ou publicação, link | ctwa_source_type, ctwa_source_id, ctwa_source_url | referral.sourceType, sourceId, sourceUrl | Atributos do contato em GET /api/v1/contacts |
| Título e texto do anúncio | ctwa_headline, ctwa_body (cortado em 500 caracteres) | referral.headline, referral.body | Atributos do contato |
| ID de clique | ctwa_clid | referral.ctwaClid | Atributos do contato |
| Origem do lead | "Anúncio Click-to-WhatsApp" | source "ctwa_ad" em contact.created | source: "ctwa_ad" |
| Um contato existente clica em um anúncio | Mantém a origem e os campos | ✓ A referência ainda chega | Sem alteração |
| Janela de ponto de entrada gratuito (72 horas) | Selo “A janela grátis do anúncio termina…” no chat | freeEntryPointExpiresAt na conversa |
Leia o anúncio na primeira mensagem
Verifique o cabeçalho X-SM-Signature e depois salve referral.ctwaClid com o lead.
{
"id": "evt_01JCA4M8ZP",
"type": "message.received",
"createdAt": "2026-10-07T09:15:04.000Z",
"workspaceId": "ws_9f2c",
"data": {
"message": {
"id": "msg_51c0",
"conversationId": "conv_8e21",
"contactId": "ct_4a7d",
"from": "+919812345678",
"type": "text",
"text": "Hi, is the festive offer still on?",
"media": null,
"reply": null,
"context": null,
"form": null,
"referral": {
"sourceType": "ad",
"sourceId": "120210000000000000",
"sourceUrl": "https://fb.me/abc123",
"headline": "Festive sale on silk sarees",
"body": "Tap to chat with us on WhatsApp",
"ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"
},
"timestamp": "2026-10-07T09:15:02.000Z"
},
"contact": {
"id": "ct_4a7d",
"phone": "+919812345678",
"name": "Asha"
}
}
}import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const app = express();
const SECRET = process.env.SM_WEBHOOK_SECRET; // the whole whsec_… string
function verify(rawBody, headers) {
const ts = headers['x-sm-timestamp'];
const sigs = headers['x-sm-signature'];
if (!/^\d+$/.test(ts ?? '') || typeof sigs !== 'string') return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = createHmac('sha256', SECRET).update(`${ts}.`).update(rawBody).digest();
return sigs.split(',').some((part) => {
const m = /^v1=([0-9a-f]{64})$/.exec(part.trim());
return m !== null && timingSafeEqual(Buffer.from(m[1], 'hex'), expected);
});
}
app.post('/webhooks/startmessaging', express.raw({ type: 'application/json' }), async (req, res) => {
if (!verify(req.body, req.headers)) return res.sendStatus(401);
res.sendStatus(200); // answer within 5 seconds, then do the work
const event = JSON.parse(req.body);
if (event.type !== 'message.received') return;
const { referral, from } = event.data.message;
if (!referral) return; // not the first message from an ad
// Any referral field can be null when Meta leaves it out.
await saveAdLead({
eventId: event.id, // delivered at least once: deduplicate on this
phone: from,
adId: referral.sourceId,
headline: referral.headline,
ctwaClid: referral.ctwaClid, // keep it for Meta's Conversions API
});
// When this lead converts, your own server sends ctwaClid to Meta's
// Conversions API. StartMessaging does not send conversions to Meta.
});import hmac, hashlib, json, os, time
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ['SM_WEBHOOK_SECRET'].encode() # the whole whsec_… string
def verify(raw_body, ts, sigs):
if not ts or not ts.isdigit() or not sigs:
return False
if abs(time.time() - int(ts)) > 300:
return False
expected = hmac.new(SECRET, f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return any(
hmac.compare_digest(part.strip()[3:], expected)
for part in sigs.split(',') if part.strip().startswith('v1=')
)
@app.post('/webhooks/startmessaging')
def startmessaging_webhook():
raw = request.get_data()
if not verify(raw, request.headers.get('X-SM-Timestamp'), request.headers.get('X-SM-Signature')):
return '', 401
event = json.loads(raw)
if event['type'] == 'message.received':
message = event['data']['message']
referral = message.get('referral')
if referral: # first message from a Click-to-WhatsApp ad
save_ad_lead(
event_id=event['id'], # deduplicate on this
phone=message['from'],
ad_id=referral.get('sourceId'),
headline=referral.get('headline'),
ctwa_clid=referral.get('ctwaClid'), # for Meta's Conversions API
)
return '', 200Anúncios Click-to-WhatsApp — Perguntas Frequentes
Eu crio os anúncios no StartMessaging?
Não. Você cria, segmenta e paga os anúncios Click-to-WhatsApp no Gerenciador de Anúncios da Meta, ou impulsiona uma publicação da sua Página do Facebook ou conta do Instagram. Direcione o anúncio para o número de WhatsApp conectado ao StartMessaging, e o StartMessaging lê o anúncio de cada nova conversa que ele iniciar.
O que o StartMessaging captura do anúncio?
Tudo o que a Meta envia na referência da primeira mensagem: o tipo de origem, o ID do anúncio ou da publicação, o link, o título, o texto do anúncio e o ID de clique (ctwaClid). Qualquer um deles pode vir vazio quando a Meta não o envia. Um novo contato guarda esses dados nos campos personalizados ctwa_source_type, ctwa_source_id, ctwa_source_url, ctwa_headline, ctwa_body (cortado em 500 caracteres) e ctwa_clid.
O que acontece quando um contato existente clica em um anúncio?
O contato mantém a origem e os campos personalizados originais; eles são definidos apenas uma vez, pela mensagem que criou o contato. A referência ainda chega no webhook message.received, para que o seu sistema registre o novo clique no anúncio.
O StartMessaging envia conversões para a API de Conversões da Meta?
Não. O StartMessaging guarda o ID de clique (ctwaClid) no contato e no webhook. Quando um lead converte, o seu próprio servidor, ou uma ferramenta de automação que você controla, envia o ctwaClid para a API de Conversões da Meta. Para creditar uma venda a uma campanha do StartMessaging, o plano Business oferece POST /api/v1/conversions: informe a venda com o telefone do cliente, e a última campanha entregue a ele dentro da sua janela de conversão recebe o crédito.
A Meta cobra pelas mensagens em um chat vindo de anúncio?
Não dentro da janela de ponto de entrada gratuito. Quando um cliente escreve a partir de um anúncio Click-to-WhatsApp e você responde a tempo, a Meta abre uma janela de ponto de entrada gratuito de 72 horas em que não cobra nada pelas mensagens daquele chat, templates incluídos. A caixa de entrada mostra o selo “A janela grátis do anúncio termina…” até lá, e a API devolve o horário de término como freeEntryPointExpiresAt na conversa. A janela não substitui a regra das 24 horas: passadas as 24 horas do cliente, você ainda precisa de um template aprovado. Depois que ela termina, valem as tarifas normais da Meta.
Posso responder automaticamente aos leads de anúncios?
Sim. Um fluxo de chatbot com o gatilho de primeira mensagem começa na primeira mensagem do contato na conversa, então recebe cada nova conversa, inclusive cliques em anúncios. Ele pode fazer perguntas, adicionar tags, mover o contato para uma etapa do funil e passar a conversa para um agente. As respostas automáticas por palavra-chave também funcionam. Como o cliente escreveu primeiro, a janela de 24 horas está aberta e você pode responder com mensagens livres. Os fluxos de chatbot fazem parte do plano Business e do teste grátis de 14 dias; as respostas automáticas por palavra-chave, dos planos Team e Business.
Posso enviar leads de anúncios para meu próprio CRM ou planilha?
Sim. Assine message.received (que traz a referência) e contact.created (que traz source "ctwa_ad"), ou sincronize com GET /api/v1/contacts e updatedSince, que retorna a origem e os atributos ctwa_* de cada contato. Zapier, Make e Pabbly Connect funcionam com seus módulos genéricos de webhook e HTTP; ainda não há apps oficiais do StartMessaging nesses marketplaces.
Páginas Relacionadas
Transforme Cliques em Anúncios em Leads Rastreados
Teste grátis de 14 dias. Conecte seu próprio número do WhatsApp Business e veja o anúncio por trás de cada nova conversa.