Seguimiento de conversiones de Ads (Meta CAPI)

Visión general

La plataforma ya captura el tráfico pago: los anuncios click-to-WhatsApp (CTWA), los anuncios que abren una conversación en Messenger (click-to-Messenger) o en Instagram Direct (click-to-Instagram Direct) y los leads de formularios de anuncio (leadgen) llegan atribuidos a su campaña de origen. El seguimiento de conversiones es el otro lado de ese ciclo: envía de vuelta a Meta los eventos que ocurren después — un lead capturado, el primer contacto, una venta cerrada — mediante la Conversions API (CAPI).

Con esto, Meta optimiza las campañas por los resultados reales (no solo por el clic) y tú mides el costo por conversión y el retorno de la inversión con datos reales.

Puntos clave:

La configuración es por bandeja de entrada (cada inbox de WhatsApp/anuncios tiene su propio destino).
Los eventos se deduplican con un identificador determinístico — la misma venta nunca se cuenta dos veces.
El token nunca aparece en la interfaz (solo su presencia y los 4 últimos caracteres).
Hoy el proveedor activo es la Meta Conversions API; Google Ads y TikTok existen como estructura preparada, pero aún no envían eventos.

La captura (CTWA/leadgen) y la conversión son módulos distintos. Este artículo trata solo del envío de eventos de vuelta a Meta. Para la captura y la atribución, consulta el artículo de Ads/CTWA/leadgen.

Requisitos previos

Módulo opt-in: tu cuenta necesita la flag ads_conversion_tracking habilitada. Es diferente de la flag de captura (growth_ads) — puedes tener la captura sin el envío de conversiones.
Permiso de administrador (toda la configuración y el disparo manual son solo para admin).
Una bandeja de entrada de un canal de Meta y un token con el permiso de eventos de ese canal:
- WhatsApp Cloud: la cuenta de WhatsApp Business (WABA) y whatsapp_business_manage_events;
- Messenger (bandeja de la Página de Facebook): la Página y page_events;
- Instagram: la cuenta profesional de Instagram e instagram_manage_events.
Las bandejas de WhatsApp Web, 360dialog o Twilio no tienen WABA — en esos casos el Dataset ID y el token se ingresan manualmente.
El inicio de sesión de la Página y el de Instagram no piden page_events ni instagram_manage_events. Para Messenger e Instagram, usa el token de la conexión con el Administrador de Anuncios de Meta (los permisos vienen de la configuración del Inicio de sesión con Facebook para empresas en el Panel de Apps de Meta) o pega un token que tenga el permiso.
Dark-ship: al crearse, la configuración nace apagada (enabled = falso). No se envía nada hasta que actives el interruptor — a propósito, para que valides antes.

Paso a paso

Abre la Configuración del Inbox de la bandeja deseada y ve a la pestaña Conversiones.
Token: marca usar el token del canal para reutilizar las credenciales de la propia bandeja (WhatsApp Cloud ya trae la WABA y un token utilizable). En canales sin WABA, pega el token de Meta.
Dataset ID: haz clic en Detectar o crear — la plataforma consulta la WABA, la Página o la cuenta de Instagram de la bandeja y completa el Dataset ID por ti (Meta devuelve el dataset existente o crea uno). En canales sin WABA, ingrésalo manualmente.
Código de prueba: ingresa el test event code (lo encuentras en el Administrador de Eventos de Meta, en Eventos de prueba).
Ejecuta un evento de prueba: la plataforma dispara LeadSubmitted y Purchase sintéticos directo a Meta, con el código de prueba. Confirma que aparecen en Eventos de prueba en el Administrador.
Solo después de que la prueba pase, activa el interruptor (enabled). A partir de ahí los eventos de ciclo de vida empiezan a enviarse de verdad.

El evento de prueba omite el interruptor principal y los disparadores (existe justamente para validar el cableado antes de salir en vivo). Requiere un código de prueba y credenciales de Meta válidas.

Configuración y opciones

Disparadores de ciclo de vida (cada uno activa/desactiva un evento):

Opción	Evento enviado	Predeterminado
`lead_on_capture`	`LeadSubmitted` cuando se captura el lead	Activado
`contact_on_first_message`	`ViewContent` en el primer mensaje del contacto	Desactivado
`purchase_on_won`	`Purchase` cuando el negocio se gana en el CRM	Activado
`purchase_on_payment`	`Purchase` cuando se confirma un pago	Activado
`custom_on_lost`	uno de los eventos admitidos, elegido en `lost_event_name`	Desactivado / sin evento

Eventos admitidos por Meta para mensajería empresarial: LeadSubmitted, QualifiedLead, ViewContent, AddToCart, InitiateCheckout y Purchase. Meta rechaza los nombres de la CAPI web (Lead, Contact, Schedule) y eventos personalizados como Lead_Lost en este flujo.
Mapa de etapa del CRM → evento (stage_event_map): asocia una etapa del embudo a uno de esos seis eventos admitidos para reportar hitos intermedios más allá de ganado/perdido.
Advanced matching: mejora la coincidencia enviando señales adicionales del usuario (siempre con hash — ningún dato personal en crudo sale de la plataforma).
Versión de la API: la versión de la API de Marketing de Meta la define la plataforma, la misma para todas las bandejas (hoy v26.0), y la pantalla solo la muestra. Por la API, el campo meta_api_version quedó obsoleto: todavía acepta solo v26.0 o v25.0, pero se ignora al enviar.
Partner agent (meta_partner_agent, predeterminado ConversaLabs): identifica tus llamadas en Meta.
Token write-only: el token se guarda y enmascara — la interfaz solo muestra que existe y los 4 últimos caracteres. Guardar con el campo en blanco mantiene el token almacenado; hay una acción explícita para borrar el token cuando sea necesario.

Messenger e Instagram

Un clic en un anuncio que abre una conversación en Messenger o Instagram Direct se convierte en un lead de anuncio con el origen Click-to-Messenger o Click-to-Instagram Direct. Aparece en la central de leads y dispara los mismos flujos que un lead de WhatsApp: el evento LeadSubmitted, las automatizaciones y los flujos del Flow Builder con el disparador lead de anuncio capturado, los follow-ups, la distribución de grupos y los webhooks de la cuenta.
Las acciones que solo existen en WhatsApp no salen por el canal equivocado: una plantilla o un flow de WhatsApp en una conversación de Messenger o de Instagram se omite y queda registrado, y la distribución de grupos registra el lead sin WhatsApp como omitido (sin WhatsApp).
Las automatizaciones pueden filtrar por el origen del lead de anuncio (Click-to-WhatsApp, formulario, Click-to-Messenger o Click-to-Instagram Direct).
Meta no tiene un clic identificado en estos canales: el evento lleva la Página y el ID del contacto en la Página (Messenger), o la cuenta de Instagram y el ID del contacto en Instagram. Las ventas y las etapas del CRM de esa conversación cuentan para el anuncio, dentro de la ventana de 7 días del lead.
Instagram es solo medición: Meta registra los eventos en el Administrador de Eventos, pero hoy no optimiza los anuncios de Instagram con ellos. La optimización por compra vale para anuncios que llevan a Messenger y a WhatsApp. La pantalla de Conversiones muestra este aviso en las bandejas de Instagram.

Leads de formulario (CRM)

Los eventos de leads de formulario de anuncio siguen el formato de la API de Conversiones para CRM de Meta: llevan el ID del lead y los campos event_source: crm y lead_event_source (el nombre del CRM, el mismo del partner agent). Sin esos campos Meta no usa el evento en la optimización por leads de conversión.

Ledger y disparo manual

Cada intento de envío se convierte en una fila del ledger de conversiones, con el estado de la entrega:

pending (en proceso), sent (entregado a Meta), failed (falló) o skipped (ignorado).
El ledger guarda solo el cuerpo con hash / sin datos personales que se envió, más la respuesta de Meta para depuración.
Cada lead tiene su ledger propio — abre el lead y verás todos los eventos enviados por él.
Cuando un intento falla o se omite, el ledger indica qué hacer (por ejemplo, el permiso que le falta al token) y conserva el motivo original de Meta para el diagnóstico.
Meta no deduplica los eventos de mensajería. La plataforma reintenta, con el mismo identificador, solo cuando está segura de que el evento no llegó: límite de llamadas, Meta no disponible o una conexión que ni siquiera se abrió. Si Meta tarda en responder después del envío, el evento queda como fallido (puede haber llegado) y no se reenvía solo: revisa el Administrador de Eventos antes de reenviarlo.

Disparo manual (admin): en un lead puedes forzar un evento — por ejemplo, registrar un Purchase de un lead que convirtió fuera del CRM. El disparo manual:

usa un identificador determinístico por (evento, lead), así que volver a hacer clic en el mismo evento deduplica (no cuenta dos veces), pero reintenta si el intento anterior falló;
solo acepta los seis eventos de mensajería empresarial indicados arriba; los valores legados Lead y Contact enviados a la API se convierten a LeadSubmitted y ViewContent;
requiere que las conversiones estén activadas en la bandeja del lead.

Informes

El informe de Ads trae las métricas de entrega de las conversiones, junto a la atribución:

Enviados (sent), fallidos (failed) e ignorados (skipped).
Valor reportado a Meta — la suma del valor de los eventos entregados (útil para verificar lo que realmente se devolvió como ingreso).

Los eventos skipped son esperables cuando un negocio no tiene atribución de anuncio: la plataforma registra el evento como ignorado (visible en la central de leads) en lugar de enviar algo sin origen.

Proveedores

Meta Conversions API — proveedor activo (v1). Envía eventos de business messaging de WhatsApp, Messenger e Instagram al dataset de tu WABA, tu Página o tu cuenta de Instagram, descubriendo el Dataset ID automáticamente cuando no se informa. Los leads de formulario salen en el formato de CRM.
Google Ads y TikTok — existen como estructura preparada en provider_settings, pero no envían eventos en esta versión. Permanecen apagados por defecto.

Casos de uso

Optimizar campañas de WhatsApp por el lead capturado y la venta cerrada, no solo por el clic.
Devolver a Meta el valor de la venta para calcular el ROAS por campaña.
Registrar manualmente un Purchase de un cliente que compró por un canal externo al CRM.
Reportar hitos intermedios del embudo mapeando etapas del CRM a eventos de Meta.

Consejos, límites y buenas prácticas

Prueba siempre primero: ejecuta el evento de prueba y confírmalo en el Administrador de Eventos antes de activar el interruptor.
Idempotencia: confía en la deduplicación determinística — ganado y pago de un mismo negocio colapsan en un único Purchase entregado.
Sin atribución = ignorado: si ves muchos skipped, verifica que las conversaciones/leads lleguen realmente con la referencia del anuncio (una captura CTWA/leadgen saludable).
Seguridad del token: nunca compartas el token; se guarda cifrado y nunca se muestra.
El envío nunca interrumpe el flujo: una falla de entrega se registra en el ledger, no detiene la atención ni el CRM.

Solución de problemas

conversions_not_enabled: la flag ads_conversion_tracking está apagada para la cuenta, o el interruptor de la bandeja está apagado. Habilita la flag y activa la configuración del inbox.
Dataset no encontrado (no_conversions_dataset): pulsa Detectar o crear otra vez. La operación es idempotente: devuelve el dataset existente o provisiona uno para la WABA. Si persiste, introduce el Dataset ID manualmente. Si todavía falla, pide al administrador de la plataforma que revise la versión de la API de Marketing, que se define para todas las bandejas.
Evento inválido (invalid_conversion_event): elige uno de los seis eventos admitidos para mensajería empresarial. Meta no acepta eventos web ni nombres personalizados en este flujo.
no_permission: al token le falta el permiso de eventos del canal (whatsapp_business_manage_events, page_events o instagram_manage_events). Vuelve a conectar el Administrador de Anuncios de Meta con el permiso o pega un token que lo tenga.
Falta la Página o el ID del contacto (Messenger/Instagram): la conversación tiene que venir de la Página o de la cuenta de Instagram conectada a la bandeja.
Falló con "puede haber llegado": Meta tardó en responder después del envío. Revisa el evento en el Administrador de Eventos y reenvíalo solo si no está allí.
El evento de prueba no aparece en el Administrador: confirma el test event code correcto y que el token y la WABA pertenezcan a la misma cuenta publicitaria; revisa en Eventos de prueba.
Eventos saliendo como skipped: el negocio no tiene atribución de anuncio — revisa la captura (CTWA/leadgen) antes del envío.