TL;DR: Whapi.Cloud incluye ctwa_clid en cada webhook de Click-to-WhatsApp bajo context.ad.ctwa, sin ninguna configuración de su parte. Léalo, guárdelo en su CRM y haga un POST a la API de Conversiones de Meta como user_data.ctwa_clid para que su inversión en anuncios de WhatsApp sea atribuible. Si context.ad está ausente, el mensaje es orgánico: omita el reporte de CAPI para ese evento. Use Lead como nombre de evento predeterminado.
¿Qué Es la Publicidad Click-to-WhatsApp?
Los anuncios Click-to-WhatsApp (CTWA) son formatos de anuncios de Meta en Facebook e Instagram. Al tocar el llamado a la acción, se abre directamente una conversación de WhatsApp, sin página de destino intermedia ni formulario que completar.
El usuario toca el anuncio, WhatsApp se abre y su primer mensaje llega directamente a su bandeja de entrada. Una vez dentro de WhatsApp, un píxel de navegador estándar no puede seguirlo. Antes de que existiera ctwa_clid, todo el gasto en anuncios de WhatsApp era prácticamente inatribuible: un lead que hizo clic en su anuncio era indistinguible de uno que escribió su número manualmente.
¿Qué Es ctwa_clid y Cómo Funciona?
Cuando un usuario toca un anuncio Click-to-WhatsApp, Meta inyecta un identificador de clic llamado ctwa_clid en la conversación.
Viaja con el primer mensaje entrante y le permite vincular el lead de WhatsApp con el anuncio exacto, la campaña y el segmento de audiencia que lo generaron.
A diferencia de un click ID de UTM, ctwa_clid vive en los metadatos del mensaje y no en un parámetro de consulta de URL. Meta lo genera en el momento del toque del anuncio y lo adjunta al objeto de referral del primer mensaje entrante.
Whapi.Cloud entrega ctwa_clid de forma nativa en cada webhook entrante que califique bajo context.ad.ctwa. Sin configuración de su parte: sin banderas especiales, sin llamadas adicionales a la API. Algunos proveedores eliminan u omiten el objeto de referral antes de que el payload llegue a su handler. Whapi.Cloud pasa el objeto de atribución completo de forma predeterminada.
Tres campos de atribución llegan juntos en el mismo evento de webhook:
-
context.ad.ctwa: el valor de
ctwa_cliden sí mismo. Este es el identificador que envía a la API de Conversiones de Meta comouser_data.ctwa_clidpara reportar la conversión offline. -
context.conversion.data: el token de deduplicación. Páselo como
event_iden su payload de CAPI. Si su configuración también activa un píxel de navegador para la misma sesión, Meta usa este token para deduplicar los eventos del servidor y del cliente, de modo que la conversión se cuente una vez, no dos. -
context.ad.source.id identifica el creativo del anuncio específico. Combínelo con
ctwa_clidcuando necesite atribución a nivel de creativo: no solo «este lead provino de la campaña X», sino «este lead provino de la variante de carrusel con ese titular e imagen específicos».
Requisitos Previos: Tres Cosas que Verificar antes de Ver ctwa_clid
Las tres condiciones deben cumplirse antes de que ctwa_clid aparezca en sus webhooks. Si falta alguna, context.ad no estará presente, independientemente de cómo esté escrito su handler de webhook.
- Una campaña Click-to-WhatsApp activa. El mensaje entrante debe originarse desde el toque de un anuncio de CTWA. Los contactos orgánicos (usuarios que encuentran su número mediante búsqueda, un enlace compartido o entrada directa) envían mensajes sin datos de referral adjuntos.
- Atribución habilitada en la configuración de WhatsApp Business. Este es el paso que la mayoría de los equipos omite. Abra la configuración de su cuenta de WhatsApp Business, encuentre la sección de Atribución de Anuncios y habilítela. Sin esta opción, Meta no incluye el objeto de referral en la conversación, y
context.adnunca aparece en el payload del webhook. - Un endpoint de webhook de Whapi.Cloud configurado. La URL de su backend debe estar registrada en el panel de Whapi.Cloud y debe ser accesible públicamente. La configuración estándar de webhook aplica: no se necesita modo de atribución especial ni permiso adicional en el lado de Whapi.Cloud.
El Webhook de Whapi.Cloud: Dónde Vive ctwa_clid
Cuando llega un mensaje con atribución de CTWA, Whapi.Cloud entrega un payload de webhook que incluye un objeto context junto con los campos estándar del mensaje. Ese objeto tiene dos sub-claves: ad (datos de la fuente del clic) y conversion (token de deduplicación).
A continuación se muestra el payload completo del webhook de Whapi.Cloud para un mensaje de Click-to-WhatsApp con atribución. Estudie el bloque context: todo lo necesario para el reporte de CAPI está ahí.
{
"messages": [
{
"id": "msg_id_123",
"from_me": false,
"type": "text",
"chat_id": "[email protected]",
"timestamp": 1714000000,
"source": "mobile",
"text": {
"body": "Hi, I saw your ad and I'm interested"
},
"context": {
"conversion": {
"data": "CONVERSION_TOKEN_ABC123",
"source": "FB_Ads"
},
"ad": {
"title": "Summer Sale — 50% Off",
"body": "Limited time offer. Click to chat now.",
"media_type": "image",
"preview_url": "https://example.com/ad-preview.jpg",
"source": {
"id": "AD_ID_987654321",
"type": "ad",
"url": "https://fb.me/adlink123"
},
"attrib": true,
"ctwa": "CTWA_CLICK_ID_1234567890"
}
},
"from": "60123456789",
"from_name": "John Doe"
}
]
}Las dos rutas a memorizar: messages[0].context.ad.ctwa es el ctwa_clid. messages[0].context.conversion.data es el token de deduplicación. Ambos son necesarios para un payload de CAPI completo.
context.ad.source.id también viaja en el mismo webhook: ese es el ID del creativo del anuncio. Un solo evento de webhook entrega tanto la atribución a nivel de usuario (ctwa_clid) como la atribución a nivel de creativo (ID del anuncio) simultáneamente. No se necesita una segunda llamada a la API para saber qué creativo vio el usuario.
Para la referencia completa de campos y ejemplos de casos extremos, consulte el artículo de la base de conocimientos de Whapi.Cloud sobre el rastreo de leads de WhatsApp desde anuncios de Meta. La especificación completa del payload de webhook entrante, incluidos todos los campos de context, está en la referencia del formato de webhooks entrantes.
Paso a Paso: Extraiga ctwa_clid y Envíelo a la API de Conversiones de Meta
Seis pasos desde la recepción del webhook hasta una conversión offline reportable en el Administrador de Anuncios de Meta. Los pasos 1–3 están en su handler de webhook; los pasos 4–6 son el POST de CAPI.
Paso 1: Acuse de recibo inmediato, luego procese. Su endpoint de webhook debe devolver un 200 antes de cualquier trabajo asíncrono. Whapi.Cloud reintenta los webhooks que expiran, lo que crea procesamiento duplicado. Responda primero, luego gestione la lógica de atribución.
Pasos 2–3: Extraiga y guarde. Lea context.ad.ctwa del payload. Si está ausente, el mensaje es orgánico: salga temprano y omita CAPI. Si está presente, guárdelo junto al registro del contacto en su CRM antes de hacer cualquier otra cosa. CAPI puede llamarse de forma asíncrona; su registro de CRM debe crearse de forma sincrónica para que no se pierda ningún lead si la llamada a CAPI falla.
// Node.js / Express — webhook handler
app.post('/webhook', async (req, res) => {
res.sendStatus(200); // Step 1: acknowledge before processing
const messages = req.body.messages || [];
for (const msg of messages) {
if (msg.from_me) continue; // skip outbound messages
const ctwaClid = msg.context?.ad?.ctwa; // Step 2: ctwa_clid
const convToken = msg.context?.conversion?.data; // deduplication token
const adId = msg.context?.ad?.source?.id; // creative-level attribution
if (!ctwaClid) continue; // organic message — no CAPI event
// Step 3: persist lead in CRM before calling CAPI
await crm.createLead({
phone: msg.from,
name: msg.from_name,
ctwa_clid: ctwaClid,
ad_id: adId,
source: 'whatsapp_ctwa',
});
// Steps 4–6: report offline conversion to Meta CAPI
await sendToMetaCAPI({ ctwaClid, convToken, phone: msg.from });
}
});Pasos 4–6: Construya y haga POST del evento de CAPI. El endpoint de la API de Conversiones de Meta es https://graph.facebook.com/v19.0/{PIXEL_ID}/events. Use Lead como nombre del evento para los flujos de CTWA equivalentes a envíos de formularios: esta es la señal de optimización correcta para el algoritmo de Meta. Pase ctwa_clid como user_data.ctwa_clid y context.conversion.data como event_id.
// Steps 4–6: Meta Conversions API POST
async function sendToMetaCAPI({ ctwaClid, convToken, phone }) {
const pixelId = process.env.META_PIXEL_ID;
const accessToken = process.env.META_CAPI_TOKEN;
const payload = {
data: [
{
event_name: 'Lead', // use 'Lead' for CTWA qualification flows
event_time: Math.floor(Date.now() / 1000),
event_id: convToken, // dedup token from context.conversion.data
action_source: 'business_messaging',
user_data: {
ctwa_clid: ctwaClid, // ctwa_clid from context.ad.ctwa
ph: hashSHA256(phone), // hashed phone (SHA-256, no leading +)
},
},
],
};
const url = `https://graph.facebook.com/v19.0/${pixelId}/events?access_token=${accessToken}`;
const resp = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
return resp.json();
}Una vez que Meta recibe el evento, la conversión aparece en el Administrador de Anuncios como un evento offline atribuido. Esto alimenta directamente el ROAS reportado de su campaña. La ventana de atribución sigue la configuración de su cuenta de Meta (predeterminada: 7 días por clic, 1 día por visualización).
Tres detalles de implementación que previenen errores de reporte:
-
Hashee el número de teléfono. Meta requiere que los campos PII transmitidos a CAPI estén hasheados con SHA-256. Elimine el signo «+» inicial antes de hashear; no lo incluya en la cadena sin procesar.
-
event_id es obligatorio si ejecuta un píxel de navegador. Cuando tanto el CAPI del servidor como un píxel de navegador se activan para la misma conversión, Meta deduplica usando
event_id. Omita este campo y el mismo lead podría contarse dos veces en sus reportes, inflando las conversiones y corrompiendo las señales de optimización de la campaña. -
No use
Purchasea menos que se confirme una transacción. UseLeadpara la calificación del primer contacto. ReservePurchasepara los flujos donde se cobra un pago dentro de la conversación de WhatsApp. Los nombres de eventos incorrectos envían señales equivocadas al algoritmo de pujas de Meta, que optimiza para el resultado incorrecto durante los ciclos de campaña posteriores.
Casos de Uso Prácticos para la Atribución con ctwa_clid
Tres escenarios donde la atribución con ctwa_clid cambia directamente la manera en que se asignan los presupuestos de marketing.
| Caso de Uso | Campo que Extrae | Resultado de Negocio |
|---|---|---|
| Rastreo de fuente de leads en CRM | context.ad.ctwa almacenado con el registro del contacto al crearlo |
El equipo de ventas ve qué campaña generó cada lead; marketing obtiene datos de ROAS de ciclo cerrado sin un sistema de etiquetado manual |
| Optimización a nivel de creativo | context.ad.source.id mapeado a la tasa de conversión de conversación a venta |
Identifique qué creativos generan conversaciones calificadas versus las de alto volumen pero no calificadas; mueva el presupuesto a las variantes que producen ingresos |
| Reporte de conversiones offline a Meta | ctwa_clid enviado a CAPI como evento Lead |
El algoritmo de optimización de Meta recibe señales de conversión reales del downstream de WhatsApp, lo que mejora la calidad del público objetivo en los ciclos de campaña posteriores |
¿Qué Pasa Si context.ad No Está en el Webhook?
No todos los mensajes entrantes provienen de un anuncio. Los contactos orgánicos encuentran su número por recomendación boca a boca, enlaces compartidos, códigos QR o búsqueda directa, y sus mensajes no llevan datos de referral.
En Whapi.Cloud, esto es sencillo de detectar: si context.ad está ausente del payload, no existe atribución de anuncios. Proteja antes de cualquier lógica de CAPI:
// Attribution guard — always run this check first
const ctwaClid = msg.context?.ad?.ctwa;
if (!ctwaClid) {
// Organic contact — create CRM record normally, skip CAPI
return;
}
// Attribution confirmed — proceed with CAPI reporting
Enviar un evento de CAPI sin un ctwa_clid válido crea ruido de atribución en el Administrador de Anuncios de Meta e infla los recuentos de conversiones reportadas. Los contactos orgánicos son valiosos — simplemente no llevan atribución de anuncios, lo cual es la representación precisa de cómo llegaron.
Whapi.Cloud expone la cadena completa de atribución de Click-to-WhatsApp — ctwa_clid, token de deduplicación e ID del creativo del anuncio — en cada webhook que califique, de forma predeterminada. ctwa_clid más Meta CAPI equivale a un ROAS comprobable y reportable para los equipos de ventas que priorizan WhatsApp. Si su proveedor actual de API de WhatsApp no expone estos datos, cada gasto en anuncios de CTWA es una caja negra sin retorno medible.
