Rastrear anuncios de WhatsApp hasta la venta

Actualizado el 25/10/2026

Para saber qué anuncio de clic a WhatsApp generó una venta, lee el objeto referral que la Cloud API envía en el webhook del mensaje recibido: trae el ID del anuncio (source_id) y un ID único del clic (ctwa_clid). Guarda esos datos junto con el contacto y la conversación y, cuando ocurra la venta, conecta el pedido con ellos. Así calculas ventas por anuncio en tu propio sistema y además puedes devolver la venta a Meta mediante la API de Conversiones.

Esta guía muestra el payload, qué significa cada campo, cómo armar la atribución en tu base de datos, cómo verificar la ventana de punto de entrada gratuito en el webhook de estados y los casos en que el dato no llega.

Qué es un anuncio Click-to-WhatsApp

Los anuncios de clic a WhatsApp (Click-to-WhatsApp o CTWA) son anuncios de Facebook e Instagram cuyo botón abre una conversación con la empresa en WhatsApp. La persona toca el anuncio, WhatsApp se abre con un mensaje prellenado y, cuando lo envía, tu integración recibe ese mensaje por el webhook con los datos del anuncio adjuntos.

Lo importante: el Administrador de anuncios muestra cuántas conversaciones generó el anuncio, pero no sabe qué pasó después. La venta se cierra en la conversación, en tu CRM o en tu checkout. Quien conecta una punta con la otra es tu integración.

El objeto referral en el webhook

Según la referencia del webhook de mensajes de texto, cuando el mensaje viene de un anuncio CTWA, llega con un objeto referral:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WABA_ID",
    "changes": [{
      "field": "messages",
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "display_phone_number": "5511999990000", "phone_number_id": "PHONE_NUMBER_ID" },
        "contacts": [{ "profile": { "name": "Ana" }, "wa_id": "5511988887777" }],
        "messages": [{
          "from": "5511988887777",
          "id": "wamid.HBgN...",
          "timestamp": "1761400000",
          "type": "text",
          "text": { "body": "¡Hola! Quiero saber más sobre el plan anual." },
          "referral": {
            "source_url": "https://fb.me/3cr4Wqqkv",
            "source_id": "120226305854810726",
            "source_type": "ad",
            "headline": "Escríbenos",
            "body": "Plan anual con soporte por WhatsApp",
            "media_type": "image",
            "image_url": "https://scontent.xx.fbcdn.net/...",
            "ctwa_clid": "Aff-n8ZTODiE79d22KtAwQKj9e_mIEOOj27vDVwFjN80dp4...",
            "welcome_message": { "text": "¡Hola! ¿Cómo podemos ayudarte?" }
          }
        }]
      }
    }]
  }]
}

Qué significa cada campo

Campo	Qué es	Uso en la atribución
`source_id`	ID del anuncio	Clave para agrupar ventas por anuncio
`source_type`	Origen (`ad` para anuncio)	Filtrar lo que vino de anuncios
`source_url`	URL del anuncio	Referencia para revisar en Facebook
`headline` / `body`	Título y texto principal del anuncio	Identificar el creativo sin consultar la API de Marketing
`media_type`	`image` o `video`	Comparar formatos
`image_url`, `video_url`, `thumbnail_url`	Medios del anuncio (según el tipo)	Mostrar el creativo en el CRM
`ctwa_clid`	ID del clic, único por clic	Enviar la conversión de vuelta a Meta
`welcome_message.text`	Texto de saludo del anuncio	Contexto para la atención

Dos observaciones de la documentación de Meta:

El ctwa_clid no llega cuando el mensaje nace de un anuncio en los Estados de WhatsApp. En ese caso, igual tienes el source_id.
El ctwa_clid es un identificador personal, único por clic, según la guía de la API de Conversiones para mensajería empresarial. Trátalo como dato personal, con la misma protección que el teléfono del cliente.

Cómo armar la atribución en tu sistema

La lógica es simple: guardar el clic cuando llega y conectar la venta con el clic cuando ocurre.

1. Guarda el referral apenas llegue el mensaje

Crea una tabla de orígenes de conversación:

CREATE TABLE origen_conversacion (
  id            BIGSERIAL PRIMARY KEY,
  wa_id         TEXT NOT NULL,
  wamid         TEXT NOT NULL UNIQUE,
  ad_id         TEXT,
  ctwa_clid     TEXT,
  headline      TEXT,
  recibido_en   TIMESTAMPTZ NOT NULL
);

Y en el manejador del webhook:

export function registrarOrigen(value, db) {
  for (const msg of value.messages ?? []) {
    const ref = msg.referral;
    if (!ref || ref.source_type !== 'ad') continue;

    db.insertarOrigen({
      wa_id: msg.from,
      wamid: msg.id,
      ad_id: ref.source_id,
      ctwa_clid: ref.ctwa_clid ?? null, // ausente en anuncios de Estados
      headline: ref.headline ?? null,
      recibido_en: new Date(Number(msg.timestamp) * 1000),
    });
  }
}

Usa el wamid como clave única: Meta puede reenviar el mismo webhook, y el UNIQUE evita duplicar el origen. Para probar con payloads de ejemplo antes de lanzar anuncios, mira cómo probar el webhook en local.

2. Conecta la venta con el último clic

Cuando se crea el pedido (en el checkout, en el CRM o por un agente), busca el origen más reciente de ese wa_id dentro de una ventana que tú defines, por ejemplo 7 o 28 días:

SELECT ad_id, ctwa_clid
FROM origen_conversacion
WHERE wa_id = $1
  AND recibido_en >= now() - interval '7 days'
ORDER BY recibido_en DESC
LIMIT 1;

Guarda ad_id y ctwa_clid en el pedido. Ese es tu modelo de último clic. Si una persona hizo clic en dos anuncios, la venta va al más reciente. Elige la ventana según tu ciclo de venta y mantén la misma regla al comparar anuncios.

Si la venta ocurre en un checkout fuera de WhatsApp, incluye un identificador del contacto en el enlace que envías en la conversación (un código de pedido o de sesión), para que el checkout pueda volver al wa_id.

3. Ponles nombre a los IDs

El source_id es un número. Para mostrar «Campaña Black Friday – Video 2» en el informe, consulta la API de Marketing con un token que tenga acceso a la cuenta publicitaria:

curl "https://graph.facebook.com/v26.0/120226305854810726?fields=name,adset{name},campaign{name}&access_token=TOKEN_CON_ADS_READ"

Guarda el resultado en caché: el nombre del anuncio cambia poco, y consultarlo en cada mensaje es un desperdicio.

4. Informe por anuncio

Con ad_id en el pedido, el informe es una consulta: conversaciones por anuncio (de la tabla de orígenes), pedidos e ingresos por anuncio (de la tabla de pedidos) y la tasa de conversión entre ambos. Suma la inversión de cada anuncio, exportada del Administrador de anuncios, y tienes el costo por venta.

Ventana de punto de entrada gratuito

Las conversaciones que empiezan por un anuncio CTWA tienen un beneficio de costo. Según la página de precios de Meta, si el usuario escribe desde un anuncio CTWA en la app de Android o iOS y la empresa responde dentro de la ventana de atención, esa respuesta no se cobra y abre una ventana de punto de entrada gratuito (FEP). Mientras está abierta, los mensajes de marketing, utilidad, autenticación y servicio no se cobran. Los mensajes de Meta Business Agent siguen cobrándose.

Sobre la duración, las fuentes oficiales no coinciden: la documentación para desarrolladores dice que la ventana puede quedar abierta hasta 7 días, y el sitio comercial de WhatsApp Business todavía habla de 72 horas. En lugar de depender de un número fijo, verifícalo en el webhook de estados. Según la referencia de estados, los mensajes enviados dentro de la ventana gratuita llegan con pricing.type igual a free_entry_point. La misma referencia lista la categoría referral_conversion para conversaciones de punto de entrada gratuito:

{
  "id": "wamid.HBgN...",
  "status": "delivered",
  "recipient_id": "5511988887777",
  "pricing": {
    "pricing_model": "PMP",
    "type": "free_entry_point",
    "category": "referral_conversion"
  }
}

Registrar el pricing de cada envío te permite sumar al informe cuánto ahorraste en mensajes por anuncio. Mira el webhook de estados de mensaje.

Dos consecuencias prácticas:

Responde rápido. La ventana gratuita solo se abre si la empresa responde dentro de la ventana de atención. Un mensaje de bienvenida automático lo resuelve.
Concentra el seguimiento. Los recordatorios y ofertas enviados dentro de la ventana gratuita no pagan la tarifa de marketing. Es un buen momento para la recuperación de PIX y carrito (PIX es el sistema de pagos instantáneos de Brasil).

Cuándo no llega el referral

Situación	Qué pasa	Qué hacer
Anuncio mostrado en los Estados de WhatsApp	Llega `referral`, pero sin `ctwa_clid`	Atribuye por `source_id`
El cliente guarda el número y escribe días después, fuera del anuncio	Mensaje común, sin referral	La conversación cuenta como orgánica en tu sistema
Webhook caído cuando llegó el mensaje	El dato se pierde si no procesas el reintento	Responde 200 rápido y procesa en una cola
Uso desde la app de escritorio o web	La ventana gratuita no aplica (la página de precios solo menciona Android e iOS)	No cuentes con la gratuidad en esos casos

Del informe a la optimización: API de Conversiones

Saber qué anuncio vende es la mitad del camino. La otra mitad es contárselo a Meta, para que la entrega de los anuncios aprenda de las ventas y no solo de las conversaciones iniciadas. Eso se hace enviando eventos (como Purchase) con el ctwa_clid a la API de Conversiones. El paso a paso está en API de Conversiones de Meta para WhatsApp.

Cómo hacerlo con Vectalk

Vectalk reenvía los webhooks en el formato de Meta, así que el objeto referral llega a tu URL tal como se describe arriba, sin conversión. Para empezar:

Conecta tu número en apps.vectalk.com.br/register.
Registra el webhook con POST /api/webhooks (documentación). Puedes registrar más de una URL por instancia, por ejemplo una para la atención y otra solo para el servicio de atribución.
Guarda referral y pricing como se muestra en este artículo.

Preguntas frecuentes

¿El referral llega en todos los mensajes de la conversación?

La documentación de Meta describe el referral en el mensaje que el usuario envía desde el anuncio. Guárdalo apenas llegue y no dependas de recibirlo de nuevo en los mensajes siguientes.

¿Qué diferencia hay entre source_id y ctwa_clid?

El source_id es el ID del anuncio: igual para todos los que hicieron clic en él. El ctwa_clid es el ID de un clic específico, de una persona. Para informes por anuncio, usa el source_id; para devolver la conversión a Meta, usa el ctwa_clid.

¿Puedo saber la campaña y el conjunto de anuncios?

Sí, consultando el ID del anuncio en la API de Marketing con un token que tenga acceso a la cuenta publicitaria. El webhook de WhatsApp solo trae el ID del anuncio y los textos del creativo.

¿La ventana gratuita es de 72 horas o de 7 días?

La documentación para desarrolladores de Meta habla de hasta 7 días; el sitio comercial de WhatsApp Business todavía dice 72 horas. Verifícalo mensaje por mensaje con pricing.type en el webhook de estados: free_entry_point indica que el mensaje no se cobró por estar dentro de la ventana.

¿Funciona con anuncios de Instagram?

Sí. Los anuncios de clic a WhatsApp pueden publicarse en Facebook e Instagram, y el mensaje llega a WhatsApp con el referral de la misma forma.

Fuentes oficiales consultadas el 25/10/2026: Webhook de mensajes de texto (referral), Webhook de estados (pricing), Precios de la plataforma, Precios en el sitio de WhatsApp Business, API de Conversiones para mensajería empresarial, Secuencias de bienvenida para CTWA, Vectalk: webhooks.

Anuncios Click-to-WhatsApp: cómo saber qué anuncio generó la venta