API de Conversiones para WhatsApp: guía práctica

Actualizado el 25/10/2026

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

Esta guía muestra los requisitos, el paso a paso, los eventos admitidos, un ejemplo en Node.js y los cuidados con duplicados y datos personales.

Por qué devolver la venta

Sin ese retorno, Meta solo ve el inicio del embudo: cuántas personas hicieron clic e iniciaron una conversación. La venta ocurre después, en la atención 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.

El primer paso es tener la atribución en tu sistema: guardar el referral del webhook y conectar el pedido con el clic. Eso está en cómo saber qué anuncio generó la venta. Este artículo empieza donde ese termina.

Requisitos

Según la guía de integración de la API de Conversiones para mensajería empresarial, para anuncios de clic a WhatsApp necesitas:

Requisito	Detalle
App de desarrollador de Meta	Creada en el panel de apps
Permiso `whatsapp_business_management`	Con acceso avanzado
Permiso `whatsapp_business_manage_events`	Con acceso avanzado; las apps que ya tienen acceso avanzado a `whatsapp_business_messaging` se aprueban automáticamente al solicitarlo
Nivel de acceso a la API de Marketing	La función «Marketing API Access Tier» en la app
Integración con la Cloud API	Alojada por Meta (la recomendada)
Token con ambos permisos	De usuario del sistema, de usuario del sistema de integración empresarial o del Registro insertado (Embedded Signup)

Para generar un token que no expire, mira token permanente con usuario del sistema.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Paso a paso

1. Obtén el waba_id

Es el ID de la cuenta de WhatsApp Business. Aparece en WhatsApp Manager y en el webhook, en el campo entry[].id.

2. Crea o recupera el dataset

El dataset es donde Meta reúne eventos de varias fuentes (sitio web, app, tienda física, conversaciones). Pertenece a la empresa. Un POST al endpoint de dataset de la cuenta de WhatsApp crea uno, o devuelve el existente:

curl -X POST "https://graph.facebook.com/v26.0/WABA_ID/dataset?access_token=TOKEN"

Un GET al mismo endpoint devuelve el dataset_id existente. La respuesta es un ID: guárdalo, es el destino de los eventos.

3. Captura el ctwa_clid

El ctwa_clid llega en el objeto referral del mensaje recibido cuando la conversación nace de un anuncio de clic a WhatsApp. Meta lo describe como un identificador personal, único por clic, y recomienda guardarlo con la conversación. No llega en anuncios mostrados en los Estados de WhatsApp.

4. Envía el evento

Cuando ocurre la conversión, envíala a /{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 es el momento de la conversión en segundos Unix. El ejemplo oficial también incluye partner_agent, un campo que usan los socios para identificarse; si integras directamente, sin socio, no aplica.

5. Verifica en el Administrador de eventos

Después del envío, el evento aparece en el Administrador de eventos, dentro del dataset. Ahí confirmas que la integración funciona.

Eventos admitidos

Según las preguntas frecuentes de la guía oficial, la API de Conversiones para mensajería empresarial admite:

Evento	Cuándo usarlo
`Purchase`	Pago confirmado
`LeadSubmitted`	La persona envió los datos pedidos (nombre, correo, interés)
`QualifiedLead`	Lead calificado por el equipo o por un agente de IA
`ViewContent`	La persona vio un producto o catálogo en la conversación
`AddToCart`	Producto agregado al carrito
`InitiateCheckout`	Enlace de pago o código PIX generado (PIX es el sistema de pagos instantáneos de Brasil)
`CartAbandoned`	Carrito no completado
`OrderCreated`	Pedido creado
`OrderShipped`	Pedido enviado
`OrderDelivered`	Pedido entregado
`OrderCanceled`	Pedido cancelado
`OrderReturned`	Pedido devuelto
`RatingProvided`	El cliente dio una nota (por ejemplo, un NPS de posventa)
`ReviewProvided`	El cliente dejó una reseña

Meta hace una salvedad: estos eventos deben representar interacciones que ocurren en la conversación. Si la compra ocurre en tu sitio o app, usa la API de Conversiones para web o para apps, con el origen correspondiente.

Ejemplo en Node.js

El ejemplo envía Purchase cuando el pedido se paga, usando el ctwa_clid guardado con la conversación. Marca el pedido como enviado para no repetir el evento, porque Meta no deduplica los eventos de esta API: la recomendación oficial es que el anunciante deduplique 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_en) return; // sin clic o ya enviado

  const cuerpo = {
    data: [{
      event_name: 'Purchase',
      event_time: Math.floor(new Date(pedido.pagado_en).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(cuerpo),
  });

  const respuesta = await r.json();
  if (!r.ok) throw new Error(`CAPI: ${respuesta.error?.message ?? r.status}`);

  await db.marcarCapiEnviado(pedido.id, new Date());
  return respuesta;
}

Si prefieres herramientas sin código, el mismo POST puede salir de un nodo HTTP en n8n.

Sin ctwa_clid: datos del cliente con hash

No toda conversión tiene ctwa_clid, por ejemplo una conversación que empezó antes de que guardaras el clic. En ese caso, la guía 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:

user_data debe incluir page_id (el ID de la página de Facebook). Sin él, el evento se rechaza, aunque tenga datos válidos.
Incluye al menos un parámetro de cliente, como ph (teléfono) o em (correo), normalizado y con hash SHA-256.
external_id no se usa para vincular eventos en este camino.
La atribución solo cubre interacciones con anuncios de los últimos 7 días y está disponible en una parte de los países.

import { createHash } from 'node:crypto';

const sha256 = (v) => createHash('sha256').update(v).digest('hex');

// teléfono solo con dígitos y código de país: 5511988887777
const user_data = {
  page_id: process.env.PAGE_ID,
  whatsapp_business_account_id: process.env.WABA_ID,
  ph: [sha256('5511988887777')],
};

Siempre que tengas el ctwa_clid, úsalo: Meta dice que vincula de forma más confiable y no tiene esas limitaciones.

Cuidados

Duplicados. Envía cada conversión una sola vez. Usa una marca en el pedido (como capi_enviado_en) o una tabla de eventos enviados.
Un dataset por página. La guía indica que solo se puede vincular un dataset a cada página. Si ya usas la API de Conversiones para tu sitio, puedes reutilizar el dataset existente; Meta dice que sumar mensajería empresarial no interfiere con la integración actual.
Datos personales. El ctwa_clid y los teléfonos con hash son datos personales. Documenta la base legal, limita el acceso y define un plazo de conservación. Si operas en Brasil, mira LGPD y WhatsApp (la LGPD es la ley brasileña de protección de datos); esto no es asesoría legal.
Token en el servidor. El token de la API de Conversiones nunca va al navegador ni a la app del cliente.

Cómo hacerlo con Vectalk

Vectalk reenvía los webhooks en el formato de Meta, así que el referral con el ctwa_clid llega a tu URL sin cambios, listo para guardarse (documentación de webhooks). La llamada a la API de Conversiones se hace desde tu servidor directamente a Meta, con una app y un token que tengan los permisos listados arriba. Si las ventas se cierran con campañas de reenganche, la recuperación de PIX y carrito dentro de la ventana gratuita abierta por el anuncio ayuda a aumentar las conversiones que vas a informar. Crea tu cuenta en apps.vectalk.com.br/register.

Preguntas frecuentes

¿Necesito el Píxel de Meta para usar la API de Conversiones en WhatsApp?

No. Para eventos de conversación, el destino es un dataset vinculado a la cuenta de WhatsApp Business, creado con la API de dataset o en el Administrador de eventos. El Píxel es para eventos del sitio web.

¿Puedo enviar una venta que ocurrió en mi sitio web?

Sí, pero no por este camino. Los eventos de mensajería empresarial deben representar interacciones dentro de la conversación. Para compras en el sitio, usa la API de Conversiones para web.

¿Cuánto tiempo después del clic puedo enviar el evento?

Con ctwa_clid, la guía no fija un plazo. Sin él, usando datos con hash, la atribución solo cubre interacciones con anuncios de los últimos 7 días; los eventos posteriores se aceptan, pero no se atribuyen.

¿Meta deduplica eventos enviados dos veces?

No en esta API. La guía oficial recomienda que el anunciante deduplique antes de enviar.

¿Qué va en custom_data?

El valor de la conversión y la moneda, por ejemplo "currency": "BRL" y "value": 297.00 para una venta de R$ 297,00 (reales brasileños).

Fuentes oficiales consultadas el 25/10/2026: API de Conversiones para mensajería empresarial, Parámetros de información del cliente, Webhook de mensajes de texto (referral), Tokens de acceso, Vectalk: webhooks.

Pon a funcionar el WhatsApp oficial de tu empresa

Crea tu cuenta, conecta tu número a la API oficial (puedes mantener la app con coexistencia) y empieza a atender y enviar mensajes.

Crear cuenta gratis

Leer la documentación

API de Conversiones de Meta para WhatsApp: devolver la venta a tus anuncios