TikTok Events API (Lower Funnel)

Si inviertes en TikTok Messaging Ads (anuncios TikTok que redirigen a WhatsApp), Brote captura el ttclid del primer mensaje del cliente y manda eventos server-side a tu Pixel TikTok cuando el cliente paga. Cierra el loop de ROAS igual que Meta — TikTok sabe qué ad generó qué venta.

Cómo funciona

1) Cliente ve tu ad TikTok → click "Send Message"
   └─ TikTok redirige a wa.me/...?ttclid=xxx

2) Brote recibe el msg vía webhook Evolution
   └─ extrae ttclid del externalAdReply.sourceUrl
   └─ guarda en contact.metadata.tiktok_attribution

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

4) Cliente paga → webhook de la pasarela aprueba
   └─ Brote dispara CompletePayment a TikTok
   └─ POST https://business-api.tiktok.com/open_api/v1.3/event/track/
   └─ body con user.{ttclid, sha256(phone), sha256(email)}

5) TikTok matchea el ttclid con el click original y atribuye en Events
   Manager / Reports.

Configurar la integración

Paso 1 — Obtener Pixel Code + Access Token

1. Ve a TikTok Business Center → Tools → Events Manager.
2. Elige tu Pixel (o crea uno).
3. Pixel Code aparece en la card (formato CXXXXXXXXXXXXXXXXX).
4. Settings → Conversions API → Generate Access Token. Copialo YA — solo se muestra una vez.
5. Event Set ID (opcional pero recomendado): es el identificador del set de eventos. Si no lo seteas, TikTok lo infiere del Pixel.

Paso 2 — (Opcional) Test Event Code

1. Events Manager → Test Events → genera código tipo TEST123.
2. Pegalo en Brote — los events van a Test Events sin contar como conversiones reales.

Paso 3 — Conectar en Brote

1. Settings → Integraciones → Pagos → baja hasta “TikTok Events API”.
2. Pega Pixel Code + Event Set ID (opcional) + Access Token + Test Code (opcional).
3. Click Conectar TikTok. Brote hace un ping con un evento Lead minimal para validar credenciales.

Precaución

TikTok responde 200 OK incluso con errores de validación (devuelve code != 0 en el body). Brote chequea eso y solo guarda credenciales si el ping responde code: 0. Si falla, te mostramos el error exacto.

Qué se manda y cuándo

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

Por ahora solo CompletePayment está automático.

Posicionamiento competitivo

Plataforma	TikTok Events API server-side
Brote	✅ ttclid capture + CompletePayment auto
respond.io	✅ “Send TikTok Lower Funnel Event” step (manual workflow)
Wati	❌
SleekFlow	❌
Manychat	🟡 Solo client-side pixel

Brote y respond.io son hoy las únicas LATAM-relevant con TikTok CAPI server-side. Diff: respond.io exige configurar el evento por workflow (paso manual); Brote lo dispara automático apenas se aprueba el pago.

Diferencia clave con Meta CAPI

• Meta usa ctwa_clid que viene en externalAdReply.ctwaClid (campo dedicado).
• TikTok usa ttclid que viene como query param en externalAdReply.sourceUrl (Brote lo parsea con regex).
• Por eso TikTok puede fallar la atribución si TikTok cambió el formato de redirect — siempre mira los logs [whatsapp.webhook] TikTok ad detected para confirmar que se capturó.

Próximos pasos

Meta CAPI (paralela)

Meta Conversions API →

Conectar Mercado Pago

Para que dispare CompletePayment →