{"id":340,"date":"2026-10-25T13:07:50","date_gmt":"2026-10-25T13:07:50","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/api-de-conversiones-meta-whatsapp\/"},"modified":"2026-10-25T13:07:58","modified_gmt":"2026-10-25T13:07:58","slug":"api-de-conversiones-meta-whatsapp","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/es\/api-de-conversiones-meta-whatsapp\/","title":{"rendered":"API de Conversiones de Meta para WhatsApp: devolver la venta a tus anuncios"},"content":{"rendered":"\n

Actualizado el 25\/10\/2026<\/em><\/p>\n\n\n\n

La API de Conversiones para mensajer\u00eda empresarial (Conversions API for Business Messaging) es el canal oficial de Meta para informar que una conversaci\u00f3n iniciada por un anuncio de clic a WhatsApp termin\u00f3 en venta, lead u otro resultado. Capturas el ctwa_clid<\/code> en el webhook, lo guardas con la conversaci\u00f3n y, cuando ocurre el evento, env\u00edas un POST<\/code> al dataset de tu cuenta de WhatsApp Business con action_source: \"business_messaging\"<\/code> y messaging_channel: \"whatsapp\"<\/code>. El evento aparece en el Administrador de eventos y se atribuye al anuncio.<\/p>\n\n\n\n

Esta gu\u00eda muestra los requisitos, el paso a paso, los eventos admitidos, un ejemplo en Node.js y los cuidados con duplicados y datos personales.<\/p>\n\n\n\n

Por qu\u00e9 devolver la venta<\/h2>\n\n\n\n

Sin ese retorno, Meta solo ve el inicio del embudo: cu\u00e1ntas personas hicieron clic e iniciaron una conversaci\u00f3n. La venta ocurre despu\u00e9s, en la atenci\u00f3n o en tu checkout, y queda invisible para el Administrador de anuncios. Con la API de Conversiones le entregas a Meta el resultado real de cada clic.<\/p>\n\n\n\n

El primer paso es tener la atribuci\u00f3n en tu sistema: guardar el referral<\/code> del webhook y conectar el pedido con el clic. Eso est\u00e1 en c\u00f3mo saber qu\u00e9 anuncio gener\u00f3 la venta<\/a>. Este art\u00edculo empieza donde ese termina.<\/p>\n\n\n\n

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

Seg\u00fan la gu\u00eda de integraci\u00f3n de la API de Conversiones para mensajer\u00eda empresarial<\/a>, para anuncios de clic a WhatsApp necesitas:<\/p>\n\n\n\n

Requisito<\/th>Detalle<\/th><\/tr><\/thead>
App de desarrollador de Meta<\/td>Creada en el panel de apps<\/td><\/tr>
Permiso whatsapp_business_management<\/code><\/td>Con acceso avanzado<\/td><\/tr>
Permiso whatsapp_business_manage_events<\/code><\/td>Con acceso avanzado; las apps que ya tienen acceso avanzado a whatsapp_business_messaging<\/code> se aprueban autom\u00e1ticamente al solicitarlo<\/td><\/tr>
Nivel de acceso a la API de Marketing<\/td>La funci\u00f3n “Marketing API Access Tier” en la app<\/td><\/tr>
Integraci\u00f3n con la Cloud API<\/td>Alojada por Meta (la recomendada)<\/td><\/tr>
Token con ambos permisos<\/td>De usuario del sistema, de usuario del sistema de integraci\u00f3n empresarial o del Registro insertado (Embedded Signup)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Para generar un token que no expire, mira token permanente con usuario del sistema<\/a>.<\/p>\n\n\n\n

Paso a paso<\/h2>\n\n\n\n

1. Obt\u00e9n el waba_id<\/h3>\n\n\n\n

Es el ID de la cuenta de WhatsApp Business. Aparece en WhatsApp Manager y en el webhook, en el campo entry[].id<\/code>.<\/p>\n\n\n\n

2. Crea o recupera el dataset<\/h3>\n\n\n\n

El dataset es donde Meta re\u00fane eventos de varias fuentes (sitio web, app, tienda f\u00edsica, conversaciones). Pertenece a la empresa. Un POST<\/code> al endpoint de dataset de la cuenta de WhatsApp crea uno, o devuelve el existente:<\/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
Un GET<\/code> al mismo endpoint devuelve el dataset_id<\/code> existente. La respuesta es un ID: gu\u00e1rdalo, es el destino de los eventos.<\/p>\n\n\n\n
3. Captura el ctwa_clid<\/h3>\n\n\n\n
El ctwa_clid<\/code> llega en el objeto referral<\/code> del mensaje recibido cuando la conversaci\u00f3n nace de un anuncio de clic a WhatsApp. Meta lo describe como un identificador personal, \u00fanico por clic, y recomienda guardarlo con la conversaci\u00f3n. No llega en anuncios mostrados en los Estados de WhatsApp.<\/p>\n\n\n\n
4. Env\u00eda el evento<\/h3>\n\n\n\n
Cuando ocurre la conversi\u00f3n, env\u00edala a \/{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> es el momento de la conversi\u00f3n en segundos Unix. El ejemplo oficial tambi\u00e9n incluye partner_agent<\/code>, un campo que usan los socios para identificarse; si integras directamente, sin socio, no aplica.<\/p>\n\n\n\n
5. Verifica en el Administrador de eventos<\/h3>\n\n\n\n
Despu\u00e9s del env\u00edo, el evento aparece en el Administrador de eventos, dentro del dataset. Ah\u00ed confirmas que la integraci\u00f3n funciona.<\/p>\n\n\n\n
Eventos admitidos<\/h2>\n\n\n\n
Seg\u00fan las preguntas frecuentes de la gu\u00eda oficial, la API de Conversiones para mensajer\u00eda empresarial admite:<\/p>\n\n\n\n
Evento<\/th>Cu\u00e1ndo usarlo<\/th><\/tr><\/thead>
Purchase<\/code><\/td>Pago confirmado<\/td><\/tr>
LeadSubmitted<\/code><\/td>La persona envi\u00f3 los datos pedidos (nombre, correo, inter\u00e9s)<\/td><\/tr>
QualifiedLead<\/code><\/td>Lead calificado por el equipo o por un agente de IA<\/td><\/tr>
ViewContent<\/code><\/td>La persona vio un producto o cat\u00e1logo en la conversaci\u00f3n<\/td><\/tr>
AddToCart<\/code><\/td>Producto agregado al carrito<\/td><\/tr>
InitiateCheckout<\/code><\/td>Enlace de pago o c\u00f3digo PIX generado (PIX es el sistema de pagos instant\u00e1neos de Brasil)<\/td><\/tr>
CartAbandoned<\/code><\/td>Carrito no completado<\/td><\/tr>
OrderCreated<\/code><\/td>Pedido creado<\/td><\/tr>
OrderShipped<\/code><\/td>Pedido enviado<\/td><\/tr>
OrderDelivered<\/code><\/td>Pedido entregado<\/td><\/tr>
OrderCanceled<\/code><\/td>Pedido cancelado<\/td><\/tr>
OrderReturned<\/code><\/td>Pedido devuelto<\/td><\/tr>
RatingProvided<\/code><\/td>El cliente dio una nota (por ejemplo, un NPS de posventa<\/a>)<\/td><\/tr>
ReviewProvided<\/code><\/td>El cliente dej\u00f3 una rese\u00f1a<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Meta hace una salvedad: estos eventos deben representar interacciones que ocurren en la conversaci\u00f3n<\/strong>. Si la compra ocurre en tu sitio o app, usa la API de Conversiones para web o para apps, con el origen correspondiente.<\/p>\n\n\n\n
Ejemplo en Node.js<\/h2>\n\n\n\n
El ejemplo env\u00eda Purchase<\/code> cuando el pedido se paga, usando el ctwa_clid<\/code> guardado con la conversaci\u00f3n. Marca el pedido como enviado para no repetir el evento, porque Meta no deduplica los eventos de esta API: la recomendaci\u00f3n oficial es que el anunciante deduplique 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_en) return; \/\/ sin clic o ya enviado\n\n  const cuerpo = {\n    data: [{\n      event_name: 'Purchase',\n      event_time: Math.floor(new Date(pedido.pagado_en).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(cuerpo),\n  });\n\n  const respuesta = await r.json();\n  if (!r.ok) throw new Error(`CAPI: ${respuesta.error?.message ?? r.status}`);\n\n  await db.marcarCapiEnviado(pedido.id, new Date());\n  return respuesta;\n}<\/code><\/pre>\n\n\n\n
Si prefieres herramientas sin c\u00f3digo, el mismo POST<\/code> puede salir de un nodo HTTP en n8n<\/a>.<\/p>\n\n\n\n
Sin ctwa_clid: datos del cliente con hash<\/h2>\n\n\n\n
No toda conversi\u00f3n tiene ctwa_clid<\/code>, por ejemplo una conversaci\u00f3n que empez\u00f3 antes de que guardaras el clic. En ese caso, la gu\u00eda oficial permite enviar datos del cliente con hash SHA-256 en lugar del clic, y Meta intenta vincular el evento con un anuncio. Reglas de ese camino:<\/p>\n\n\n\n