TikTok Events API

Esta guía explica cómo configurar los eventos de la Events API que AdTarget envía a TikTok cuando los usuarios se unen a tu canal de Telegram.

¿Cuándo se envían los eventos?

AdTarget envía un evento a TikTok solo para uniones atribuidas — es decir, uniones donde AdTarget puede vincular la unión a Telegram con un clic específico en un anuncio en tu página de destino. Esto requiere que el invite_link esté presente en el webhook de Telegram.

Los eventos se envían cuando un usuario hace clic en tu enlace de invitación rastreado y Telegram lo reporta en el webhook (confiable para canales privados).

Los eventos NO se envían para uniones orgánicas — usuarios que encuentran tu canal a través de búsqueda, enlaces directos o mensajes reenviados. Estas uniones aún aparecen en tu panel de AdTarget pero se marcan como “orgánicas”.

Limitación de canales públicos: Debido a una limitación de la API de Telegram, incluso los usuarios que hacen clic en tu enlace rastreado pueden ser tratados como uniones orgánicas en canales públicos. La app de Telegram (especialmente Android) a menudo convierte las uniones por enlace de invitación en “uniones directas” para canales públicos, eliminando los datos de atribución. Saber más →

Tipos de eventos disponibles

AdTarget mapea sus tipos de eventos a los eventos estándar de TikTok:

Evento AdTarget	Evento TikTok	Ideal para	Optimización TikTok
Lead	SubmitForm	Campañas de generación de leads	Optimiza para envíos de formularios
Purchase	Purchase	Campañas enfocadas en compras	Optimiza para acciones de compra
CompleteRegistration	CompleteRegistration	Campañas enfocadas en registros	Optimiza para acciones de registro
Subscribe	Subscribe	Campañas de suscripción	Optimiza para intención de suscripción
Custom	Tu nombre personalizado	Seguimiento especializado	Optimización personalizada

Elegir el evento correcto

¿Ejecutando anuncios de generación de leads? Usa Lead (se mapea al SubmitForm de TikTok) — Esto le dice a TikTok “esta persona envió un formulario / se convirtió en lead”.

¿Vendiendo un producto o servicio? Usa Purchase — Ideal cuando quieres que TikTok optimice para compradores. Combínalo con un value y currency en la configuración de conversión de tu canal para optimización basada en valor.

¿Ejecutando campañas de registro? Usa CompleteRegistration — Señala una acción de registro completada.

¿Promoviendo una suscripción a un canal? Usa Subscribe — Coincide con la acción del usuario (unirse = suscribirse).

¿Necesitas un evento no estándar? Usa Custom — Te permite definir tu propio nombre de evento para escenarios de seguimiento especializados.

Consejo: Haz coincidir tu tipo de evento con el objetivo de tu campaña en TikTok Ads Manager para mejores resultados.

Configuración de eventos

Los tipos de eventos se configuran por canal. Cada canal tiene como predeterminado CompleteRegistration cuando se detecta por primera vez.

Para cambiar el tipo de evento de un canal:

Ve a los Settings de tu sitio → pestaña Channels
Haz clic en Setup (o Edit) en la fila del canal
Selecciona tu tipo de evento en el diálogo
Haz clic en Save

Parámetros de eventos

Cada evento que AdTarget envía a TikTok incluye estos parámetros:

Parámetros obligatorios

Parámetro	Descripción
`event`	El nombre del evento TikTok (SubmitForm, Purchase, etc.)
`timestamp`	Marca de tiempo ISO 8601 de la unión
`event_id`	ID único de deduplicación

Parámetros de atribución

Parámetro	Descripción
`context.ad.callback`	El `ttclid` del clic en el anuncio (TikTok Click ID)

Datos de usuario

Parámetro	Fuente	¿Hasheado?
`context.user.external_id`	ID de usuario de Telegram	Sí (SHA-256)
`context.ip`	IP de la visita a la página de destino	No (enviado tal cual)
`context.user_agent`	Navegador de la visita a la página de destino	No (enviado tal cual)

El external_id (ID de usuario de Telegram) se hashea con SHA-256 antes de enviarlo, como requiere TikTok. La dirección IP y el user agent se envían tal cual según las especificaciones de la Events API de TikTok.

Propiedades del evento

Parámetro	Descripción
`properties.value`	Valor del evento (si está configurado por canal)
`properties.currency`	Código de moneda (por defecto `"USD"`)
`properties.content_name`	Título del canal o nombre personalizado de la config del canal

Deduplicación de eventos

AdTarget incluye un event_id único con cada evento para prevenir duplicados:


event_id: "adtarget_{conversion_id}"

Esto asegura que la misma conversión no se cuente dos veces, incluso si se reintenta.

Prueba de eventos

Prueba en producción

La forma más confiable de probar de extremo a extremo:

Haz clic en tu propio anuncio de TikTok (o usa un anuncio de prueba)
Visita tu página de destino
Únete a tu canal de Telegram a través del enlace de invitación rastreado
Revisa el TikTok Events Manager en 5-10 minutos

Verificar en TikTok Ads Manager

Ve a Assets → Events → Web Events → Manage
Revisa la pestaña Events
Busca tu tipo de evento con marcas de tiempo recientes
Verifica que el evento muestre como “Received”

Coincidencia de eventos

TikTok hace coincidir tus eventos con usuarios para la atribución. Mayor calidad de coincidencia significa mejor optimización.

Factores de calidad de coincidencia

Factor	Impacto
ttclid presente	Alto - Atribución directa por clic
User agent + IP	Medio - Coincidencia probabilística
External ID	Medio - Coincidencia entre dispositivos

Mejorar la calidad de coincidencia

Captura el ttclid: Asegúrate de que la URL de tu página de destino preserve el parámetro ttclid
Envía eventos rápidamente: Menor tiempo entre clic y conversión mejora la coincidencia
Recorrido de usuario consistente: Mantén a los usuarios en tu dominio antes de redirigirlos a Telegram

Configuraciones comunes de eventos

Generación de leads


AdTarget Event: Lead → TikTok Event: SubmitForm
When: User joins channel
Use Case: "Get subscribers" campaigns

Seguimiento de compras


AdTarget Event: Purchase → TikTok Event: Purchase
When: User joins channel
Use Case: "Buy now" campaigns with value-based optimization

Suscripción a contenido


AdTarget Event: Subscribe → TikTok Event: Subscribe
When: User joins channel
Use Case: "Subscribe to channel" campaigns

Solución de problemas

¿Los eventos no coinciden?

Verifica que el ttclid esté en la URL de la página de destino
Verifica que el TikTok Pixel también esté en la página de destino
Asegúrate de que las cookies no estén bloqueadas

¿Baja tasa de coincidencia de eventos?

Reduce el tiempo entre clic y conversión
Verifica que el ttclid se esté capturando de la URL
Asegúrate de que IP y user agent estén disponibles

¿Eventos duplicados?

AdTarget maneja la deduplicación automáticamente vía event_id
Si ves duplicados, contacta al soporte

Mejores prácticas

Haz coincidir el tipo de evento con el objetivo de campaña para mejor optimización
Usa el mismo tipo de evento consistentemente dentro de una campaña
Monitorea la entrega de eventos en TikTok Events Manager regularmente
Prueba antes de escalar el gasto publicitario

Próximos pasos

¡Tu integración con TikTok está completa! Comienza a ejecutar anuncios y observa cómo tus conversiones llegan a TikTok.

¿Necesitas ayuda para optimizar? Contacta a nuestro equipo de soporte.