## 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

1. Abre la **Configuración del Inbox** de la bandeja deseada y ve a la pestaña **Conversiones**.
2. **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.
3. **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.
4. **Código de prueba**: ingresa el **test event code** (lo encuentras en el Administrador de Eventos
   de Meta, en *Eventos de prueba*).
5. **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.
6. 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.

## Ver también

- [Ads, CTWA y leadgen con atribución](/hc/ajuda/articles/growth-marketing-ads-ctwa-leadgen-es)
- [Visión general del Growth & Marketing Studio](/hc/ajuda/articles/growth-marketing-overview-es)
- [Visión general de Pagos](/hc/ajuda/articles/payments-overview-es)