Meta Conversions API — atribución ROAS

Si inviertes en anuncios de Meta que llevan a conversación (Click-to-WhatsApp, Click-to-Instagram, Click-to-Messenger), quieres saber qué ad generó qué venta. Brote cierra el loop completo: detecta el ad de entrada, guarda la atribución en el contacto, y cuando ese contacto paga envía un evento Purchase a tu Pixel via Conversions API.

Nota

La atribución funciona en los tres canales oficiales de Meta: WhatsApp, Instagram DM y Messenger. Es una feature exclusiva del plan Business, igual que el MCP server.

Cómo funciona el flow

1) Cliente ve tu ad Meta → click "Send Message" / "Enviar mensaje"
   └─ Meta agrega el click id en el primer msg del canal
       (ctwa_clid en WhatsApp; el equivalente en Instagram / Messenger)

2) Brote recibe el msg por el canal oficial de Meta
   └─ extrae el click id del ad + sourceId + título
   └─ guarda en contact.metadata.attribution (first-touch)

3) Cliente conversa con tu agente IA → recibe link MP/Flow/Khipu

4) Cliente paga → webhook de la pasarela aprueba el pago
   └─ Brote dispara sendConversionForContact()
   └─ POST a https://graph.facebook.com/v18.0/{pixel_id}/events
       body: { event_name: "Purchase", user_data: { ph: sha256(phone),
               ctwa_clid }, custom_data: { value, currency } }

5) Meta matchea el ctwa_clid con el click original y atribuye la
   conversión al ad correcto en tu Events Manager.

Configurar la integración

Paso 1 — Obtener Pixel ID + Access Token

1. Ve a Events Manager.
2. Elige tu Pixel (o crea uno si no tienes).
3. Pixel ID aparece en la card del pixel (15-16 dígitos).
4. Configuración → Conversions API → Generar token de acceso. Copialo YA — se muestra una sola vez. Si lo pierdes, generas uno nuevo y revocas el viejo.

Paso 2 — (Opcional) Test Event Code

Durante el setup, quieres validar que los eventos llegan sin contar como conversiones reales:

1. En Events Manager → Test Events → genera código tipo TEST12345.
2. Pegalo en Brote cuando conectes. Los eventos van a aparecer en “Test Events” y no contar en tus reports de ROAS.
3. Una vez validado, saca el code y los eventos empiezan a contar como conversiones reales.

Paso 3 — Conectar en Brote

1. Settings → Integraciones → Pagos → baja hasta “Meta Conversions API”.
2. Pega Pixel ID + Access Token + Test Code (opcional).
3. Click Conectar Meta. Brote hace un ping con un evento Lead para validar que las credenciales funcionan.

Consejo

Si el ping falla con “invalid_credentials”, probablemente:

• El Access Token no es del Pixel que pegaste
• El Access Token expiró (regeneralo)
• El Pixel ID está mal escrito (solo dígitos, sin espacios)

Qué se manda y cuándo

Evento	Cuándo	Custom data
Purchase	Cuando MP / Flow / Khipu aprueba el pago	value (CLP), currency, content_name
Lead (futuro)	Cuando lifecycle pasa a mql o sql	—
InitiateCheckout (futuro)	Cuando agente manda link de pago	value, currency

Por ahora solo Purchase está activo automático. El resto los activamos cuando midamos volumen de uso.

Logs y debugging

Cada evento enviado queda registrado en la tabla meta_conversion_events con:

• status: sent | failed
• error_detail si falló
• payload con custom_data
• fbtrace_id que Meta asigna (útil para correlacionar con tu Events Manager)

Para ver el log de los últimos eventos, puedes correr una query en Supabase Studio:

select event_name, status, event_value, ctwa_clid, error_detail, sent_at
from public.meta_conversion_events
where organization_id = '<tu_org_id>'
order by sent_at desc
limit 20;

En Events Manager → Test Events vas a ver los eventos llegando casi en tiempo real (10-30 seg de delay).

Atribución visible en el inbox

En la conversación de cualquier contacto que vino por un Meta Ad, el panel lateral muestra un badge azul ”🎯 Vino por Meta Ad” con:

• Título del ad (si Meta lo mandó)
• Fecha de captura

Útil para que los humanos del equipo sepan que ese cliente costó plata de Ads y priorizar la respuesta.

Límites y costos

• Meta Conversions API es gratis — no cobran por evento.
• Rate limit: 200 events/second por Pixel ID (más que suficiente para PYMEs LATAM).
• Brote trackea events_sent_this_month en meta_integrations para visibilidad (no es cap, solo info).

Posicionamiento competitivo

Plataforma	Meta CAPI integrado
Brote	✅ click id (WhatsApp/IG/Messenger) + Purchase auto desde MP/Flow/Khipu
respond.io	✅ “Send Conversions API Event” step (manual en workflow)
Wati	🟡 Solo Pixel client-side (no CAPI server)
SleekFlow	❌

Brote y respond.io son hoy las únicas con CAPI server-side en LATAM-relevant. Diff: respond.io requiere configurar el evento por workflow; Brote lo dispara automático cuando hay pago, sin que toques nada después de conectar.

Próximos pasos

Click-to-WhatsApp Ads guía

Cómo crear un ad CTWA en Meta →

Conectar Mercado Pago

Para que dispare Purchase events →

Etapas del ciclo (Lead/MQL)

Próximamente: eventos automáticos al cambiar lifecycle