Respuesta corta
La API de Conversiones para mensajería le avisa a Meta qué pasó después de que alguien tocó tu anuncio de Click to WhatsApp: si se calificó, si compró. Cada evento viaja con el ctwa_clid del clic y el ID de tu cuenta de WhatsApp Business, contra el dataset que Meta crea desde esa cuenta. Sin esa señal, tus campañas optimizan por chats baratos, no por ventas.
Una campaña de mensajes a WhatsApp le pide a Meta conversaciones, y Meta cumple: trae la mayor cantidad de chats al menor costo. Lo que Meta no sabe es cuáles de esos chats terminaron en una venta y cuáles fueron curiosos que preguntaron el precio y desaparecieron. Esa información vive en tu WhatsApp, no en el Administrador de anuncios. La API de Conversiones es el camino para devolvérsela.
¿Qué es la API de Conversiones para mensajería?
Es la variante de la Conversions API de Meta pensada para conversaciones (en la documentación en inglés, Conversions API for Business Messaging). Funciona de servidor a servidor: tu sistema le manda a Meta un evento —por ejemplo, «este lead se calificó» o «este cliente compró»— y Meta lo ata al clic del anuncio que abrió la conversación. No hay pixel, no depende del navegador del cliente y no hace falta que nadie visite tu sitio web.
La pieza que hace posible esa atadura es el ctwa_clid (click ID de Click to WhatsApp): un identificador único que Meta genera cuando alguien toca tu anuncio y que llega adjunto al primer mensaje de esa persona, dentro del objeto referral del webhook. Si querés entender ese objeto en detalle, lo explicamos en cómo saber de qué anuncio viene cada chat.
¿Por qué tus anuncios de WhatsApp optimizan por chats baratos?
Porque es lo único que Meta puede medir por su cuenta. El algoritmo aprende de las señales que recibe: si la única señal es «se abrió un chat», va a buscar más personas parecidas a las que abren chats, compren o no. Cuando le mandás eventos de calidad, el aprendizaje cambia de objetivo. Ya no busca gente que escribe, busca gente parecida a la que se calificó o compró.
Por eso la señal tiene que ser honesta y llegar a tiempo. Un evento que llega tarde no se procesa, y un evento que exagera la calidad de un lead le enseña al algoritmo a buscar el perfil equivocado.
¿Qué necesitás antes de mandar el primer evento?
- Tu número en la plataforma de WhatsApp Business (la API). El ctwa_clid llega en el webhook de mensajes. Si no recibís webhooks, no tenés el dato que ata el evento al clic.
- El dataset que Meta crea desde tu cuenta de WhatsApp Business. Se obtiene con una llamada POST /{WABA_ID}/dataset. La llamada es segura de repetir: si el dataset ya existe, te devuelve el mismo. No sirve el pixel de tu sitio web ni un dataset creado a mano.
- La página de Facebook asociada a ese dataset. Es un paso que se hace una sola vez en el Administrador de eventos: el dataset tiene que tener asociadas tanto la cuenta de WhatsApp Business como la página.
- Un token con permiso sobre ese dataset. El botón «Generar token de acceso» del Administrador de eventos crea un token atado a un solo dataset. Lo más estable es un token de usuario del sistema del portfolio comercial, con la cuenta de WhatsApp, el dataset, la página y la cuenta publicitaria asignadas como activos.
- Un clic real para probar. Meta valida el ctwa_clid contra clics verdaderos. Hasta que no te escriba al menos una persona desde un anuncio, no tenés con qué hacer una prueba.
¿Qué campos lleva cada evento?
| Campo | Valor | Para qué sirve |
|---|---|---|
| event_name | Un evento estándar (LeadSubmitted, QualifiedLead, Purchase…) o una conversión personalizada | Dice qué pasó |
| event_time | Fecha en formato Unix, de hace 7 días como máximo | Dice cuándo pasó |
| action_source | business_messaging | Marca que el evento viene de una conversación |
| messaging_channel | Indica el canal de mensajería | |
| user_data.ctwa_clid | El valor tal cual llegó en el referral, sin hashear | Ata el evento al clic del anuncio |
| user_data.whatsapp_business_account_id | El ID de tu cuenta de WhatsApp Business | Identifica la cuenta que recibió el chat |
| custom_data.value y currency | Monto y moneda, solo cuando hay un monto real | Le da valor a una compra |
Dos diferencias con la API de Conversiones de un sitio web confunden a mucha gente. La primera: el ctwa_clid no se hashea, va crudo. La segunda: el identificador de la cuenta es el whatsapp_business_account_id, no el ID de la página de Facebook. En nuestras pruebas contra un dataset real, mandar page_id devolvía una respuesta exitosa y el evento no aparecía en ningún lado.
¿Qué eventos podés mandar?
Meta acepta estos eventos estándar para mensajería: Purchase, LeadSubmitted, InitiateCheckout, AddToCart, ViewContent, OrderCreated, OrderShipped, OrderDelivered, OrderCanceled, OrderReturned, CartAbandoned, QualifiedLead, RatingProvided y ReviewProvided. También podés usar conversiones personalizadas que tengas creadas en el Administrador de eventos.
La forma más ordenada de elegirlos es partir de tu embudo de ventas. Cada etapa que representa un avance real se traduce en un evento, y las etapas que significan que el lead se perdió no se traducen en nada:
| Etapa del embudo | Evento sugerido | Cuándo se manda |
|---|---|---|
| Interesado | LeadSubmitted | Pidió información concreta o dejó sus datos |
| Calificado | QualifiedLead | Cumple lo que tu negocio define como un buen lead |
| Negociación | InitiateCheckout | Está por pagar: presupuesto enviado, link de pago, reserva |
| Cliente | Purchase | Pagó, con el monto real si lo conocés |
| Perdido o descartado | Ninguno | No hay evento negativo: se deja de reportar |
Las reglas que te ahorran semanas
Un evento por pedido
El campo event_time acepta como máximo 7 días hacia atrás. Si mandás varios eventos juntos y uno solo está vencido, Meta rechaza el pedido entero y no procesa ninguno. Mandar un evento por pedido evita que un evento viejo arrastre a los que estaban bien.
Meta no deduplica: deduplicás vos
La documentación lo dice sin vueltas: Meta no ayuda a deduplicar los eventos de mensajería. Si tu sistema reintenta un envío o dos personas del equipo mueven al mismo cliente, Meta cuenta dos compras. La protección tiene que estar de tu lado: guardá qué evento ya mandaste para cada clic y no lo repitas.
Nunca reportes hacia atrás
No existe un evento negativo ni una forma de retractar lo que ya mandaste. Si un lead que reportaste como calificado después se cae, lo único honesto es no mandar nada más. Por la misma razón, conviene que la progresión sea solo hacia adelante: si un contacto ya se reportó como calificado, volver a «interesado» no debería disparar otro evento.
No inventes montos
Un Purchase con un monto inventado o promediado le enseña a Meta una rentabilidad que no existe. Si no sabés el monto exacto de una venta, usá un valor fijo que definas una sola vez para todas —tu ticket típico, por ejemplo— en lugar de estimarlo caso por caso. Y cuando el monto real existe, mandá ese.
¿Cómo probás que los eventos llegan?
- Abrí la pestaña Probar eventos del dataset en el Administrador de eventos y copiá el código de prueba (test_event_code).
- Mandá un evento con ese código y con un ctwa_clid real, tomado de un chat que haya llegado desde un anuncio.
- Confirmá que el evento aparece en la pestaña de prueba. Si Meta responde con un error, leé los campos error_user_title y error_user_msg: ahí está el dato accionable, no en el mensaje genérico.
- Cuando la prueba funcione, sacá el código de prueba y dejá que salgan los eventos reales.
Errores comunes y cómo resolverlos
Estos son los errores que vimos al poner la integración en producción contra un dataset real. Los primeros cuatro son la misma causa de fondo —dataset o identificador equivocado— mostrándose de distintas formas a medida que corregís una pieza por vez.
«No WhatsApp Business Account Associated To Dataset»
Causa: estás mandando eventos a un dataset que no está asociado a tu cuenta de WhatsApp Business, normalmente el pixel del sitio web. Solución: pedí el dataset correcto con POST /{WABA_ID}/dataset y usá ese ID en todos los envíos.
«Mismatching Page Id And Ctwa Clid»
Causa: el evento identifica la cuenta con un ID de página que no corresponde al clic. Suele aparecer cuando se intenta arreglar el error anterior agregando page_id en lugar de cambiar de dataset. Solución: identificá la cuenta con whatsapp_business_account_id y mandá al dataset de la cuenta de WhatsApp Business.
«Mismatching Page and Dataset»
Causa: la página y el dataset del evento no pertenecen a la misma configuración. Solución: la misma que antes. Volvé al dataset que devuelve POST /{WABA_ID}/dataset y dejá de mandar page_id.
«no Page associated to dataset»
Causa: el dataset es el correcto y ya tiene la cuenta de WhatsApp Business, pero le falta la página de Facebook. Solución: asociá la página al dataset desde el Administrador de eventos. Es un paso único; después no vuelve a aparecer.
Error con subcódigo 2804087
Causa: el ctwa_clid no corresponde a un clic real. Pasa cuando se prueba con un valor inventado o copiado de un ejemplo. Solución: usá el ctwa_clid de un mensaje que haya llegado de verdad desde un anuncio.
El pedido devuelve éxito pero el evento no aparece
Causa probable: estás mandando page_id en lugar de whatsapp_business_account_id. Solución: cambiá el identificador y repetí la prueba con un código de prueba activo.
¿Qué pasa si el cliente compra después de los 7 días?
Ese evento ya no se puede mandar. Es un caso frecuente: la persona pregunta hoy y paga en tres semanas. Por eso conviene reportar también las etapas que suceden dentro de la semana —interesado, calificado, negociación—. Son las que efectivamente le enseñan a la campaña, y la compra tardía la medís del lado de tu negocio.
Preguntas frecuentes
¿Necesito el pixel de mi sitio web para esto?
No. La API de Conversiones para mensajería no usa el pixel ni el navegador del cliente. Los eventos salen de tu servidor y se atan al clic del anuncio con el ctwa_clid. De hecho, usar el ID del pixel como dataset es la causa más común de que la integración falle.
¿Tengo que hashear el ctwa_clid?
No. A diferencia del email o el teléfono en la API de Conversiones web, el ctwa_clid se manda tal cual llegó en el mensaje. Si lo hasheás, Meta no puede encontrar el clic y el evento no se atribuye a ningún anuncio.
¿Por qué algunos chats de anuncios no traen ctwa_clid?
Según la documentación de Meta, los mensajes que vienen de anuncios ubicados en los Estados de WhatsApp no incluyen el ctwa_clid. Esos chats igual traen los datos del anuncio, pero no se pueden usar para mandar eventos de conversión.
¿Meta descarta un evento si lo mando dos veces?
No. Meta no deduplica los eventos de mensajería, así que un reintento o un doble clic en tu sistema se cuenta como dos conversiones. La forma segura es guardar qué evento ya enviaste para cada clic y bloquear el segundo envío antes de que salga.
¿Qué evento conviene usar para optimizar la campaña?
Uno que pase dentro de los 7 días posteriores al clic y que ocurra con cierta frecuencia. Si tus ventas se cierran rápido, Purchase. Si tardan semanas, conviene optimizar por QualifiedLead o InitiateCheckout, que llegan a tiempo y siguen separando a los curiosos de los compradores.