Sepa Qué Anuncio Inició Cada Chat de WhatsApp
Cuando alguien toca su anuncio Click-to-WhatsApp o publicación promocionada, su primer mensaje trae el anuncio. StartMessaging lo guarda en el nuevo contacto, lo muestra en el CRM y lo envía a sus sistemas por webhook, para que ningún lead de anuncio llegue anónimo.
✦ Prueba gratis de 14 días · Tu propio número de WhatsApp Business · Meta factura los mensajes directamente
El Anuncio Llega con el Primer Mensaje
Usted crea y paga los anuncios en el Administrador de anuncios de Meta. Cuando un cliente toca uno y envía su primer mensaje, WhatsApp adjunta una referencia: el tipo de origen, el ID del anuncio o publicación, su enlace, el título, el texto del anuncio y un ID de clic (ctwaClid). StartMessaging la lee en cuanto el mensaje llega a su bandeja compartida.
- Funciona con anuncios Click-to-WhatsApp y publicaciones promocionadas
- Se capturan el título, el texto, el ID y el enlace del anuncio o publicación
- ID de clic (ctwaClid) guardado para sus reportes de conversión
- Una etiqueta “La ventana gratis del anuncio termina…” mientras la ventana gratis de 72 horas de Meta está abierta
Cada Lead de Anuncio Llega al CRM con Su Anuncio
Un contacto creado por un clic en un anuncio recibe el origen "Anuncio Click-to-WhatsApp" y el anuncio como campos personalizados: ctwa_source_type, ctwa_source_id, ctwa_source_url, ctwa_headline, ctwa_body y ctwa_clid. Abra el contacto y una tarjeta "Desde un anuncio Click-to-WhatsApp" muestra el anuncio que tocó. Los campos se definen una sola vez, con ese primer mensaje. Un contacto que ya tenía conserva su origen y campos originales, y la referencia igual llega en el webhook message.received.
- Origen del lead registrado como "Anuncio Click-to-WhatsApp"
- Datos del anuncio guardados como campos personalizados, definidos una vez
- Visible en la página del contacto junto a etiquetas y notas
Del Toque en el Anuncio al Lead Calificado
1. Publique el anuncio en el Administrador de anuncios de Meta
Cree un anuncio Click-to-WhatsApp, o promocione una publicación con botón de WhatsApp, que abra un chat con el número que conectó a StartMessaging.
2. El cliente toca y escribe
Su primer mensaje llega a la bandeja compartida del equipo con la referencia del anuncio adjunta.
3. El contacto se crea con el anuncio
Un contacto nuevo recibe el origen ctwa_ad y los campos personalizados ctwa_*. Sus sistemas reciben la referencia en message.received y el origen en contact.created.
4. Enrute el lead
Un flujo de chatbot con el disparador de primer mensaje recibe cada chat nuevo, incluidos los clics en anuncios: haga preguntas de calificación, agregue una etiqueta, mueva el contacto a una etapa del embudo y asigne un agente.
5. Reporte la conversión usted mismo
Cuando el lead compra, su propio sistema envía el ctwaClid guardado a la API de Conversiones de Meta; StartMessaging no envía conversiones a Meta por usted. Para acreditar la venta a una campaña de StartMessaging, infórmela con POST /api/v1/conversions en el plan Business.
Una Referencia, Tres Lugares para Usarla
Cualquier campo de la referencia puede venir vacío cuando Meta no lo envía.
| Datos del anuncio | En el contacto (CRM) | Webhook message.received | API REST |
|---|---|---|---|
| Tipo de origen, ID del anuncio o publicación, enlace | ctwa_source_type, ctwa_source_id, ctwa_source_url | referral.sourceType, sourceId, sourceUrl | Atributos del contacto en GET /api/v1/contacts |
| Título y texto del anuncio | ctwa_headline, ctwa_body (recortado a 500 caracteres) | referral.headline, referral.body | Atributos del contacto |
| ID de clic | ctwa_clid | referral.ctwaClid | Atributos del contacto |
| Origen del lead | "Anuncio Click-to-WhatsApp" | source "ctwa_ad" en contact.created | source: "ctwa_ad" |
| Un contacto existente hace clic en un anuncio | Conserva su origen y campos | ✓ La referencia igual llega | Sin cambios |
| Ventana de punto de entrada gratuito (72 horas) | Etiqueta “La ventana gratis del anuncio termina…” en el chat | freeEntryPointExpiresAt en la conversación |
Lea el anuncio desde el primer mensaje
Verifique el encabezado X-SM-Signature y luego guarde referral.ctwaClid con el lead.
{
"id": "evt_01JCA4M8ZP",
"type": "message.received",
"createdAt": "2026-10-07T09:15:04.000Z",
"workspaceId": "ws_9f2c",
"data": {
"message": {
"id": "msg_51c0",
"conversationId": "conv_8e21",
"contactId": "ct_4a7d",
"from": "+919812345678",
"type": "text",
"text": "Hi, is the festive offer still on?",
"media": null,
"reply": null,
"context": null,
"form": null,
"referral": {
"sourceType": "ad",
"sourceId": "120210000000000000",
"sourceUrl": "https://fb.me/abc123",
"headline": "Festive sale on silk sarees",
"body": "Tap to chat with us on WhatsApp",
"ctwaClid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a"
},
"timestamp": "2026-10-07T09:15:02.000Z"
},
"contact": {
"id": "ct_4a7d",
"phone": "+919812345678",
"name": "Asha"
}
}
}import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';
const app = express();
const SECRET = process.env.SM_WEBHOOK_SECRET; // the whole whsec_… string
function verify(rawBody, headers) {
const ts = headers['x-sm-timestamp'];
const sigs = headers['x-sm-signature'];
if (!/^\d+$/.test(ts ?? '') || typeof sigs !== 'string') return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = createHmac('sha256', SECRET).update(`${ts}.`).update(rawBody).digest();
return sigs.split(',').some((part) => {
const m = /^v1=([0-9a-f]{64})$/.exec(part.trim());
return m !== null && timingSafeEqual(Buffer.from(m[1], 'hex'), expected);
});
}
app.post('/webhooks/startmessaging', express.raw({ type: 'application/json' }), async (req, res) => {
if (!verify(req.body, req.headers)) return res.sendStatus(401);
res.sendStatus(200); // answer within 5 seconds, then do the work
const event = JSON.parse(req.body);
if (event.type !== 'message.received') return;
const { referral, from } = event.data.message;
if (!referral) return; // not the first message from an ad
// Any referral field can be null when Meta leaves it out.
await saveAdLead({
eventId: event.id, // delivered at least once: deduplicate on this
phone: from,
adId: referral.sourceId,
headline: referral.headline,
ctwaClid: referral.ctwaClid, // keep it for Meta's Conversions API
});
// When this lead converts, your own server sends ctwaClid to Meta's
// Conversions API. StartMessaging does not send conversions to Meta.
});import hmac, hashlib, json, os, time
from flask import Flask, request
app = Flask(__name__)
SECRET = os.environ['SM_WEBHOOK_SECRET'].encode() # the whole whsec_… string
def verify(raw_body, ts, sigs):
if not ts or not ts.isdigit() or not sigs:
return False
if abs(time.time() - int(ts)) > 300:
return False
expected = hmac.new(SECRET, f'{ts}.'.encode() + raw_body, hashlib.sha256).hexdigest()
return any(
hmac.compare_digest(part.strip()[3:], expected)
for part in sigs.split(',') if part.strip().startswith('v1=')
)
@app.post('/webhooks/startmessaging')
def startmessaging_webhook():
raw = request.get_data()
if not verify(raw, request.headers.get('X-SM-Timestamp'), request.headers.get('X-SM-Signature')):
return '', 401
event = json.loads(raw)
if event['type'] == 'message.received':
message = event['data']['message']
referral = message.get('referral')
if referral: # first message from a Click-to-WhatsApp ad
save_ad_lead(
event_id=event['id'], # deduplicate on this
phone=message['from'],
ad_id=referral.get('sourceId'),
headline=referral.get('headline'),
ctwa_clid=referral.get('ctwaClid'), # for Meta's Conversions API
)
return '', 200Anuncios Click-to-WhatsApp — Preguntas Frecuentes
¿Creo los anuncios en StartMessaging?
No. Usted crea, segmenta y paga los anuncios Click-to-WhatsApp en el Administrador de anuncios de Meta, o promociona una publicación de su página de Facebook o cuenta de Instagram. Dirija el anuncio al número de WhatsApp que conectó a StartMessaging, y StartMessaging lee el anuncio de cada chat nuevo que inicie.
¿Qué captura StartMessaging del anuncio?
Todo lo que Meta envía en la referencia del primer mensaje: el tipo de origen, el ID del anuncio o publicación, su enlace, el título, el texto del anuncio y el ID de clic (ctwaClid). Cualquiera puede venir vacío cuando Meta no lo envía. Un contacto nuevo los guarda en los campos personalizados ctwa_source_type, ctwa_source_id, ctwa_source_url, ctwa_headline, ctwa_body (recortado a 500 caracteres) y ctwa_clid.
¿Qué pasa cuando un contacto existente hace clic en un anuncio?
El contacto conserva su origen y campos personalizados originales; se definen una sola vez, con el mensaje que creó el contacto. La referencia igual llega en el webhook message.received, así su propio sistema puede registrar el nuevo clic en el anuncio.
¿StartMessaging envía conversiones a la API de Conversiones de Meta?
No. StartMessaging guarda el ID de clic (ctwaClid) en el contacto y en el webhook. Cuando un lead convierte, su propio servidor, o una herramienta de automatización que usted controla, envía el ctwaClid a la API de Conversiones de Meta. Para acreditar una venta a una campaña de StartMessaging, el plan Business ofrece POST /api/v1/conversions: informe la venta con el teléfono del cliente, y la última campaña entregada a él dentro de su ventana de conversión recibe el crédito.
¿Meta cobra los mensajes en un chat que llega de un anuncio?
No dentro de la ventana de punto de entrada gratuito. Cuando un cliente escribe desde un anuncio Click-to-WhatsApp y usted responde a tiempo, Meta abre una ventana de punto de entrada gratuito de 72 horas en la que no cobra nada por los mensajes de ese chat, plantillas incluidas. La bandeja de entrada muestra la etiqueta “La ventana gratis del anuncio termina…” hasta entonces, y la API devuelve la hora de fin como freeEntryPointExpiresAt en la conversación. La ventana no reemplaza la regla de las 24 horas: pasadas las 24 horas del cliente, sigue necesitando una plantilla aprobada. Cuando termina, se aplican las tarifas normales de Meta.
¿Puedo responder automáticamente a los leads de anuncios?
Sí. Un flujo de chatbot con el disparador de primer mensaje se inicia con el primer mensaje del contacto en el chat, así que recibe cada chat nuevo, incluidos los clics en anuncios. Puede hacer preguntas, agregar etiquetas, mover el contacto a una etapa del embudo y pasar el chat a un agente. Las respuestas automáticas por palabra clave también funcionan. Como el cliente escribió primero, la ventana de 24 horas está abierta y puede responder con mensajes libres. Los flujos de chatbot están en el plan Business y en la prueba gratis de 14 días; las respuestas automáticas por palabra clave, en Team y Business.
¿Puedo enviar los leads de anuncios a mi propio CRM u hoja de cálculo?
Sí. Suscríbase a message.received (trae la referencia) y a contact.created (trae source "ctwa_ad"), o sincronice con GET /api/v1/contacts y updatedSince, que devuelve el origen y los atributos ctwa_* de cada contacto. Zapier, Make y Pabbly Connect funcionan con sus módulos genéricos de webhook y HTTP; todavía no hay apps oficiales de StartMessaging en esos marketplaces.
Páginas Relacionadas
Convierta Clics en Anuncios en Leads Rastreados
Prueba gratuita de 14 días. Conecte su propio número de WhatsApp Business y vea el anuncio detrás de cada chat nuevo.