{"id":338,"date":"2026-10-25T13:07:49","date_gmt":"2026-10-25T13:07:49","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/api-de-conversoes-meta-whatsapp\/"},"modified":"2026-10-25T13:07:51","modified_gmt":"2026-10-25T13:07:51","slug":"api-de-conversoes-meta-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/api-de-conversoes-meta-whatsapp\/","title":{"rendered":"API de Convers\u00f5es da Meta para WhatsApp: enviar a venda de volta aos an\u00fancios"},"content":{"rendered":"\n

Atualizado em 25\/10\/2026<\/em><\/p>\n\n\n\n

A API de Convers\u00f5es para mensagens comerciais (Conversions API for Business Messaging) \u00e9 o canal oficial da Meta para avisar que uma conversa iniciada por an\u00fancio de clique para o WhatsApp virou venda, lead ou outro resultado. Voc\u00ea captura o ctwa_clid<\/code> no webhook, guarda junto da conversa e, quando o evento acontece, envia um POST<\/code> para o dataset da sua conta do WhatsApp com action_source: \"business_messaging\"<\/code> e messaging_channel: \"whatsapp\"<\/code>. O evento aparece no Gerenciador de Eventos e passa a ser atribu\u00eddo ao an\u00fancio.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Por que enviar a venda de volta<\/h2>\n\n\n\n

Sem esse retorno, a Meta s\u00f3 enxerga o come\u00e7o do funil: quantas pessoas clicaram e iniciaram uma conversa. A venda acontece depois, no atendimento ou no seu checkout, e fica invis\u00edvel para o Gerenciador de An\u00fancios. Com a API de Convers\u00f5es, voc\u00ea entrega \u00e0 Meta o resultado real de cada clique.<\/p>\n\n\n\n

O primeiro passo \u00e9 ter a atribui\u00e7\u00e3o no seu sistema: guardar o referral<\/code> do webhook e ligar o pedido ao clique. Isso est\u00e1 em como saber qual an\u00fancio gerou a venda<\/a>. Este artigo come\u00e7a de onde aquele termina.<\/p>\n\n\n\n

Requisitos<\/h2>\n\n\n\n

Pelo guia de integra\u00e7\u00e3o da API de Convers\u00f5es para mensagens comerciais<\/a>, para an\u00fancios de clique para o WhatsApp voc\u00ea precisa de:<\/p>\n\n\n\n

Requisito<\/th>Detalhe<\/th><\/tr><\/thead>
App de desenvolvedor da Meta<\/td>Criado no painel de apps<\/td><\/tr>
Permiss\u00e3o whatsapp_business_management<\/code><\/td>Com acesso avan\u00e7ado<\/td><\/tr>
Permiss\u00e3o whatsapp_business_manage_events<\/code><\/td>Com acesso avan\u00e7ado; quem j\u00e1 tem acesso avan\u00e7ado a whatsapp_business_messaging<\/code> tem aprova\u00e7\u00e3o autom\u00e1tica ao pedir<\/td><\/tr>
N\u00edvel de acesso \u00e0 API de Marketing<\/td>Recurso “Marketing API Access Tier” no app<\/td><\/tr>
Integra\u00e7\u00e3o com a Cloud API<\/td>Hospedada pela Meta (a recomendada)<\/td><\/tr>
Token com as duas permiss\u00f5es<\/td>De usu\u00e1rio do sistema, de usu\u00e1rio do sistema de integra\u00e7\u00e3o empresarial ou do Cadastro Incorporado<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Para gerar um token que n\u00e3o expira, veja token permanente com usu\u00e1rio do sistema<\/a>.<\/p>\n\n\n\n

Passo a passo<\/h2>\n\n\n\n

1. Descubra o waba_id<\/h3>\n\n\n\n

\u00c9 o ID da conta do WhatsApp Business (conta de mensagens). Ele aparece no WhatsApp Manager e no webhook, no campo entry[].id<\/code>.<\/p>\n\n\n\n

2. Crie ou recupere o dataset<\/h3>\n\n\n\n

O dataset \u00e9 onde a Meta re\u00fane eventos de v\u00e1rias origens (site, app, loja f\u00edsica, conversas). Ele pertence \u00e0 empresa. Um POST<\/code> no endpoint de dataset da conta do WhatsApp cria um, ou devolve o que j\u00e1 existe:<\/p>\n\n\n\n

curl -X POST \"https:\/\/graph.facebook.com\/v26.0\/WABA_ID\/dataset?access_token=TOKEN\"<\/code><\/pre>\n\n\n\n
Um GET<\/code> no mesmo endpoint retorna o dataset_id<\/code> existente. A resposta \u00e9 um ID: guarde, ele \u00e9 o destino dos eventos.<\/p>\n\n\n\n
3. Capture o ctwa_clid<\/h3>\n\n\n\n
O ctwa_clid<\/code> vem no objeto referral<\/code> da mensagem recebida quando a conversa nasce de um an\u00fancio de clique para o WhatsApp. A Meta o descreve como um identificador pessoal, \u00fanico por clique, e orienta guard\u00e1-lo com a conversa. Ele n\u00e3o vem em an\u00fancios exibidos no Status do WhatsApp.<\/p>\n\n\n\n
4. Envie o evento<\/h3>\n\n\n\n
Quando a convers\u00e3o acontece, envie para \/{DATASET_ID}\/events<\/code>:<\/p>\n\n\n\n
curl -X POST \"https:\/\/graph.facebook.com\/v26.0\/DATASET_ID\/events?access_token=TOKEN\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"data\": [\n      {\n        \"event_name\": \"Purchase\",\n        \"event_time\": 1761400000,\n        \"action_source\": \"business_messaging\",\n        \"messaging_channel\": \"whatsapp\",\n        \"user_data\": {\n          \"whatsapp_business_account_id\": \"WABA_ID\",\n          \"ctwa_clid\": \"ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4...\"\n        },\n        \"custom_data\": {\n          \"currency\": \"BRL\",\n          \"value\": 297.00\n        }\n      }\n    ]\n  }'<\/code><\/pre>\n\n\n\n
event_time<\/code> \u00e9 o momento da convers\u00e3o em segundos Unix. O exemplo oficial tamb\u00e9m traz partner_agent<\/code>, campo usado por parceiros para se identificar; se voc\u00ea integra direto, sem parceiro, ele n\u00e3o se aplica.<\/p>\n\n\n\n
5. Confira no Gerenciador de Eventos<\/h3>\n\n\n\n
Depois do envio, o evento aparece no Gerenciador de Eventos, dentro do dataset. \u00c9 ali que voc\u00ea valida se a integra\u00e7\u00e3o est\u00e1 chegando.<\/p>\n\n\n\n
Eventos aceitos<\/h2>\n\n\n\n
Segundo as perguntas frequentes do guia oficial, a API de Convers\u00f5es para mensagens comerciais aceita:<\/p>\n\n\n\n
Evento<\/th>Quando usar<\/th><\/tr><\/thead>
Purchase<\/code><\/td>Pagamento confirmado<\/td><\/tr>
LeadSubmitted<\/code><\/td>Pessoa enviou os dados pedidos (nome, e-mail, interesse)<\/td><\/tr>
QualifiedLead<\/code><\/td>Lead qualificado pelo time ou pela IA<\/td><\/tr>
ViewContent<\/code><\/td>Pessoa viu um produto ou cat\u00e1logo na conversa<\/td><\/tr>
AddToCart<\/code><\/td>Item adicionado ao carrinho<\/td><\/tr>
InitiateCheckout<\/code><\/td>Link de pagamento ou PIX gerado<\/td><\/tr>
CartAbandoned<\/code><\/td>Carrinho n\u00e3o conclu\u00eddo<\/td><\/tr>
OrderCreated<\/code><\/td>Pedido criado<\/td><\/tr>
OrderShipped<\/code><\/td>Pedido enviado<\/td><\/tr>
OrderDelivered<\/code><\/td>Pedido entregue<\/td><\/tr>
OrderCanceled<\/code><\/td>Pedido cancelado<\/td><\/tr>
OrderReturned<\/code><\/td>Pedido devolvido<\/td><\/tr>
RatingProvided<\/code><\/td>Cliente deu uma nota (por exemplo, NPS no p\u00f3s-venda<\/a>)<\/td><\/tr>
ReviewProvided<\/code><\/td>Cliente deixou uma avalia\u00e7\u00e3o<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
A Meta faz uma ressalva: esses eventos devem representar intera\u00e7\u00f5es que acontecem na conversa<\/strong>. Se a compra acontece no seu site ou app, use a API de Convers\u00f5es para web ou para apps, com a origem correspondente.<\/p>\n\n\n\n
Exemplo em Node.js<\/h2>\n\n\n\n
O exemplo abaixo envia o Purchase<\/code> quando o pedido \u00e9 pago, usando o ctwa_clid<\/code> gravado na conversa. Ele marca o pedido como enviado para n\u00e3o repetir o evento, porque a Meta n\u00e3o deduplica eventos dessa API: a recomenda\u00e7\u00e3o oficial \u00e9 que o anunciante fa\u00e7a a deduplica\u00e7\u00e3o antes de enviar.<\/p>\n\n\n\n
const GRAPH = 'https:\/\/graph.facebook.com\/v26.0';\nconst { META_CAPI_TOKEN, DATASET_ID, WABA_ID } = process.env;\n\nexport async function enviarCompra(pedido, db) {\n  if (!pedido.ctwa_clid || pedido.capi_enviado_em) return; \/\/ sem clique ou j\u00e1 enviado\n\n  const corpo = {\n    data: [{\n      event_name: 'Purchase',\n      event_time: Math.floor(new Date(pedido.pago_em).getTime() \/ 1000),\n      action_source: 'business_messaging',\n      messaging_channel: 'whatsapp',\n      user_data: { whatsapp_business_account_id: WABA_ID, ctwa_clid: pedido.ctwa_clid },\n      custom_data: { currency: 'BRL', value: pedido.total },\n    }],\n  };\n\n  const r = await fetch(`${GRAPH}\/${DATASET_ID}\/events?access_token=${META_CAPI_TOKEN}`, {\n    method: 'POST',\n    headers: { 'Content-Type': 'application\/json' },\n    body: JSON.stringify(corpo),\n  });\n\n  const resposta = await r.json();\n  if (!r.ok) throw new Error(`CAPI: ${resposta.error?.message ?? r.status}`);\n\n  await db.marcarCapiEnviado(pedido.id, new Date());\n  return resposta;\n}<\/code><\/pre>\n\n\n\n
Se voc\u00ea prefere ferramentas sem c\u00f3digo, o mesmo POST<\/code> pode sair de um n\u00f3 HTTP no n8n<\/a>.<\/p>\n\n\n\n
Sem ctwa_clid: dados do cliente com hash<\/h2>\n\n\n\n
Nem toda convers\u00e3o tem ctwa_clid<\/code>, por exemplo uma conversa que come\u00e7ou antes de voc\u00ea 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\u00fancio. Regras desse caminho:<\/p>\n\n\n\n