Atualizado em 25/10/2026
A API de Conversões para mensagens comerciais (Conversions API for Business Messaging) é o canal oficial da Meta para avisar que uma conversa iniciada por anúncio de clique para o WhatsApp virou venda, lead ou outro resultado. Você captura o ctwa_clid no webhook, guarda junto da conversa e, quando o evento acontece, envia um POST para o dataset da sua conta do WhatsApp com action_source: "business_messaging" e messaging_channel: "whatsapp". O evento aparece no Gerenciador de Eventos e passa a ser atribuído ao anúncio.
Este guia mostra os requisitos, o passo a passo, os eventos aceitos, um exemplo em Node.js e os cuidados com duplicidade e dados pessoais.
Por que enviar a venda de volta
Sem esse retorno, a Meta só enxerga o começo do funil: quantas pessoas clicaram e iniciaram uma conversa. A venda acontece depois, no atendimento ou no seu checkout, e fica invisível para o Gerenciador de Anúncios. Com a API de Conversões, você entrega à Meta o resultado real de cada clique.
O primeiro passo é ter a atribuição no seu sistema: guardar o referral do webhook e ligar o pedido ao clique. Isso está em como saber qual anúncio gerou a venda. Este artigo começa de onde aquele termina.
Requisitos
Pelo guia de integração da API de Conversões para mensagens comerciais, para anúncios de clique para o WhatsApp você precisa de:
| Requisito | Detalhe |
|---|---|
| App de desenvolvedor da Meta | Criado no painel de apps |
Permissão whatsapp_business_management | Com acesso avançado |
Permissão whatsapp_business_manage_events | Com acesso avançado; quem já tem acesso avançado a whatsapp_business_messaging tem aprovação automática ao pedir |
| Nível de acesso à API de Marketing | Recurso “Marketing API Access Tier” no app |
| Integração com a Cloud API | Hospedada pela Meta (a recomendada) |
| Token com as duas permissões | De usuário do sistema, de usuário do sistema de integração empresarial ou do Cadastro Incorporado |
Para gerar um token que não expira, veja token permanente com usuário do sistema.
Passo a passo
1. Descubra o waba_id
É o ID da conta do WhatsApp Business (conta de mensagens). Ele aparece no WhatsApp Manager e no webhook, no campo entry[].id.
2. Crie ou recupere o dataset
O dataset é onde a Meta reúne eventos de várias origens (site, app, loja física, conversas). Ele pertence à empresa. Um POST no endpoint de dataset da conta do WhatsApp cria um, ou devolve o que já existe:
curl -X POST "https://graph.facebook.com/v26.0/WABA_ID/dataset?access_token=TOKEN"Um GET no mesmo endpoint retorna o dataset_id existente. A resposta é um ID: guarde, ele é o destino dos eventos.
3. Capture o ctwa_clid
O ctwa_clid vem no objeto referral da mensagem recebida quando a conversa nasce de um anúncio de clique para o WhatsApp. A Meta o descreve como um identificador pessoal, único por clique, e orienta guardá-lo com a conversa. Ele não vem em anúncios exibidos no Status do WhatsApp.
4. Envie o evento
Quando a conversão acontece, envie para /{DATASET_ID}/events:
curl -X POST "https://graph.facebook.com/v26.0/DATASET_ID/events?access_token=TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": [
{
"event_name": "Purchase",
"event_time": 1761400000,
"action_source": "business_messaging",
"messaging_channel": "whatsapp",
"user_data": {
"whatsapp_business_account_id": "WABA_ID",
"ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4..."
},
"custom_data": {
"currency": "BRL",
"value": 297.00
}
}
]
}'event_time é o momento da conversão em segundos Unix. O exemplo oficial também traz partner_agent, campo usado por parceiros para se identificar; se você integra direto, sem parceiro, ele não se aplica.
5. Confira no Gerenciador de Eventos
Depois do envio, o evento aparece no Gerenciador de Eventos, dentro do dataset. É ali que você valida se a integração está chegando.
Eventos aceitos
Segundo as perguntas frequentes do guia oficial, a API de Conversões para mensagens comerciais aceita:
| Evento | Quando usar |
|---|---|
Purchase | Pagamento confirmado |
LeadSubmitted | Pessoa enviou os dados pedidos (nome, e-mail, interesse) |
QualifiedLead | Lead qualificado pelo time ou pela IA |
ViewContent | Pessoa viu um produto ou catálogo na conversa |
AddToCart | Item adicionado ao carrinho |
InitiateCheckout | Link de pagamento ou PIX gerado |
CartAbandoned | Carrinho não concluído |
OrderCreated | Pedido criado |
OrderShipped | Pedido enviado |
OrderDelivered | Pedido entregue |
OrderCanceled | Pedido cancelado |
OrderReturned | Pedido devolvido |
RatingProvided | Cliente deu uma nota (por exemplo, NPS no pós-venda) |
ReviewProvided | Cliente deixou uma avaliação |
A Meta faz uma ressalva: esses eventos devem representar interações que acontecem na conversa. Se a compra acontece no seu site ou app, use a API de Conversões para web ou para apps, com a origem correspondente.
Exemplo em Node.js
O exemplo abaixo envia o Purchase quando o pedido é pago, usando o ctwa_clid gravado na conversa. Ele marca o pedido como enviado para não repetir o evento, porque a Meta não deduplica eventos dessa API: a recomendação oficial é que o anunciante faça a deduplicação antes de enviar.
const GRAPH = 'https://graph.facebook.com/v26.0';
const { META_CAPI_TOKEN, DATASET_ID, WABA_ID } = process.env;
export async function enviarCompra(pedido, db) {
if (!pedido.ctwa_clid || pedido.capi_enviado_em) return; // sem clique ou já enviado
const corpo = {
data: [{
event_name: 'Purchase',
event_time: Math.floor(new Date(pedido.pago_em).getTime() / 1000),
action_source: 'business_messaging',
messaging_channel: 'whatsapp',
user_data: { whatsapp_business_account_id: WABA_ID, ctwa_clid: pedido.ctwa_clid },
custom_data: { currency: 'BRL', value: pedido.total },
}],
};
const r = await fetch(`${GRAPH}/${DATASET_ID}/events?access_token=${META_CAPI_TOKEN}`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(corpo),
});
const resposta = await r.json();
if (!r.ok) throw new Error(`CAPI: ${resposta.error?.message ?? r.status}`);
await db.marcarCapiEnviado(pedido.id, new Date());
return resposta;
}Se você prefere ferramentas sem código, o mesmo POST pode sair de um nó HTTP no n8n.
Sem ctwa_clid: dados do cliente com hash
Nem toda conversão tem ctwa_clid, por exemplo uma conversa que começou antes de você passar a gravar o clique. Nesse caso, o guia oficial permite enviar dados do cliente com hash SHA-256 no lugar do clique, e a Meta tenta casar o evento com um anúncio. Regras desse caminho:
user_dataprecisa terpage_id(o ID da página do Facebook). Sem ele, o evento é rejeitado, mesmo com dados válidos.- Inclua pelo menos um parâmetro de cliente, como
ph(telefone) ouem(e-mail), normalizado e com hash SHA-256. external_idnão é usado para casar eventos nesse caminho.- A atribuição vale só para interações com anúncio dos últimos 7 dias e está disponível apenas em parte dos países.
import { createHash } from 'node:crypto';
const sha256 = (v) => createHash('sha256').update(v).digest('hex');
// telefone só com dígitos e código do país: 5511988887777
const user_data = {
page_id: process.env.PAGE_ID,
whatsapp_business_account_id: process.env.WABA_ID,
ph: [sha256('5511988887777')],
};Sempre que tiver o ctwa_clid, prefira ele: a própria Meta diz que ele casa de forma mais confiável e não tem essas limitações.
Cuidados
- Duplicidade. Envie cada conversão uma vez. Use uma marca no pedido (como
capi_enviado_em) ou uma tabela de eventos enviados. - Um dataset por página. O guia informa que só é possível vincular um dataset a cada página. Se você já usa a API de Conversões para o site, dá para reaproveitar o dataset existente; a Meta diz que acrescentar mensagens comerciais não interfere na integração atual.
- Dados pessoais. O
ctwa_clide os telefones com hash são dados pessoais. Registre a base legal, limite quem acessa e defina prazo de guarda. Veja LGPD e WhatsApp, lembrando que o texto não substitui a orientação de um advogado. - Token no servidor. O token da API de Conversões nunca vai para o navegador nem para o app do cliente.
Como fazer com a Vectalk
A Vectalk repassa os webhooks no formato da Meta, então o referral com ctwa_clid chega na sua URL sem conversão, pronto para ser gravado (documentação de webhooks). A chamada da API de Conversões é feita do seu servidor direto para a Meta, com um app e um token que tenham as permissões listadas acima. Se a venda é fechada por campanhas de reengajamento, a recuperação de PIX e carrinho dentro da janela gratuita aberta pelo anúncio ajuda a aumentar o número de conversões que você vai reportar.
Para o panorama da API, veja o guia da API oficial do WhatsApp e o artigo sobre webhook da API do WhatsApp. Crie sua conta em apps.vectalk.com.br/register.
Perguntas frequentes
Preciso do Pixel da Meta para usar a API de Conversões no WhatsApp?
Não. Para eventos de conversa, o destino é um dataset ligado à conta do WhatsApp Business, criado pela API de dataset ou pelo Gerenciador de Eventos. O Pixel é para eventos de site.
Posso enviar a venda que aconteceu no meu site?
Sim, mas não por esse caminho. Os eventos de mensagens comerciais devem representar interações dentro da conversa. Para compras no site, use a API de Conversões para web.
Quanto tempo depois do clique posso enviar o evento?
Com ctwa_clid, o guia não fixa um prazo. Sem ele, usando dados com hash, a atribuição só vale para interações com anúncio dos últimos 7 dias; eventos posteriores são aceitos, mas não atribuídos.
A Meta deduplica eventos enviados duas vezes?
Não nessa API. O guia oficial recomenda que o anunciante faça a deduplicação antes de enviar.
Que valor colocar em custom_data?
O valor da conversão e a moeda, por exemplo "currency": "BRL" e "value": 297.00 para uma venda de R$ 297,00.
Fontes oficiais consultadas em 25/10/2026: API de Conversões para mensagens comerciais, Parâmetros de informações do cliente, Webhook de mensagens de texto (referral), Tokens de acesso, Vectalk: webhooks.