Skip to Content
¡Rastrea tus conversiones de Telegram con Meta Ads — comienza en minutos!
Referencia de APIPostbacks

Postbacks salientes

Los postbacks envían los nuevos eventos de conversión de AdTarget a tu servidor. Son independientes de la API REST entrante: las claves API, las solicitudes, la atribución y los envíos a las plataformas publicitarias existentes siguen funcionando.

Eventos de Telegram

La primera sección reenvía actualizaciones de Telegram sin procesar, no conversiones publicitarias. Elige un destino y selecciona business_message (mensajes privados Business), business_connection, chat_join_request y/o chat_member (entradas, salidas y cambios de estado).

La configuración corresponde a un bot en toda la cuenta, no solo a un sitio web. El destino recibe el contenido de los mensajes y las identidades de Telegram presentes en las actualizaciones seleccionadas. Configura únicamente un backend que controles. El historial de envíos pertenece al sitio en el que se configuró inicialmente el destino.

Los nuevos reenvíos genéricos envían un cuerpo JSON con update_id y el objeto de actualización de Telegram seleccionado, sin modificaciones. Utilizan los encabezados de firma y entrega X-AdTarget-* descritos a continuación, una cola persistente y hasta seis intentos. Los identificadores de actualización de Telegram repetidos se deduplican dentro del historial de envíos conservado. Estos reenvíos no crean eventos Lead, Purchase ni otros eventos publicitarios.

Integración existente de TSA / Ross

El reenvío existente de TSA se muestra con su URL actual y los tipos de Telegram activados. Conserva su destino /telegram/proxy, la autenticación X-Forward-Secret / X-Forward-Timestamp, el contenido original de Telegram enriquecido con información de procedencia y su política de reintentos existente. No utiliza el protocolo HMAC genérico ni los nuevos interruptores de conversión. Sigue siendo el único emisor de TSAWelcomeBot: no se añade automáticamente un segundo emisor, no se cambia el secreto, no se reenvía el historial ni se migra el receptor. Sus envíos anteriores no se añaden retroactivamente al historial de envíos genéricos.

Esta integración existente protegida es de solo lectura en este editor. Al activar nuevos reenvíos para otros bots, no se sustituye esta integración.

Eventos de conversión (opcional)

Despliega Eventos de conversión — opcional para reenviar las nuevas conversiones registradas en AdTarget, incluidas las recibidas a través de la API REST entrante. Estos interruptores no controlan el reenvío de Telegram descrito anteriormente.

Configurar el envío de conversiones

Abre Sitio → Configuración → Postbacks, introduce una URL HTTPS pública, selecciona los tipos de eventos y activa los envíos. Guarda, copia el secreto de firma que se muestra una sola vez y elige Enviar prueba. La cola normalmente inicia los envíos en menos de un minuto. Solo el propietario del sitio puede modificar la configuración; la vista previa del administrador es de solo lectura.

Tipos compatibles: Lead, Purchase, CompleteRegistration, Subscribe, Contact y Custom. Seleccionar Custom incluye todos los nombres personalizados; utiliza data.customEventName para distinguirlos. Son tipos de conversión, no visitas a páginas, entradas o salidas de Telegram sin procesar ni etapas de negocio derivadas como QFTD. Una entrada utiliza el evento de conversión configurado para ese canal.

Solo se envían las nuevas conversiones creadas después de la activación. No se reenvían el historial existente, las modificaciones posteriores del valor ni las conversiones ya existentes reutilizadas por la API entrante. No hace falta migrar el historial. Los eventos sin un sitio identificado no se pueden enviar al endpoint de un sitio.

Guardar la configuración cancela los envíos pendientes de la configuración anterior. Desactivar detiene los envíos en cola; una solicitud que ya esté en curso puede finalizar. Utiliza un nombre de host público que resuelva a IPv4, con HTTPS en el puerto 443. Las direcciones privadas y las redirecciones están bloqueadas.

Solicitud

AdTarget envía una solicitud POST con Content-Type: application/json:

{
  "version": 1,
  "event": "Purchase",
  "occurredAt": 1789300000000,
  "data": {
    "conversionId": "conversion-id",
    "websiteId": "atid_example",
    "telegramUserId": 123456789,
    "value": 97,
    "currency": "EUR",
    "contentName": "VIP"
  }
}

occurredAt es una marca de tiempo Unix en milisegundos. Los campos opcionales se omiten cuando no están presentes. No se incluyen nombres, direcciones de correo electrónico, números de teléfono, direcciones IP, claves API ni credenciales publicitarias. Una prueba utiliza event: "test" y un mensaje de ejemplo; no crea ninguna conversión ni envía nada a tus píxeles publicitarios.

Verificar la autenticidad

Guarda el secreto en tu servidor. Comprueba estos encabezados:

  • X-AdTarget-Delivery-Id: identificador estable entre reintentos; utilízalo para deduplicar el procesamiento.
  • X-AdTarget-Timestamp: marca de tiempo Unix en segundos, actualizada en cada intento.
  • X-AdTarget-Signature: sha256= seguido del HMAC-SHA256 hexadecimal de timestamp + "." + rawRequestBody, firmado con tu secreto.

Verifica la firma sobre los bytes originales del cuerpo antes de analizar el JSON, rechaza las marcas de tiempo fuera de un intervalo de cinco minutos y compara las firmas en tiempo constante. Guarda el identificador de entrega de forma atómica junto con tu operación de negocio para que un reintento no pueda repetirla. Devuelve un estado 2xx después de aceptar la solicitud de forma persistente.

Fiabilidad

La entrega es al menos una vez, no exactamente una vez. Si se agota el tiempo de espera después de que tu servidor haya aceptado un evento, puede producirse un duplicado. Se realizan hasta seis intentos en total, con intervalos crecientes. Las redirecciones HTTP y las demás respuestas fuera de 2xx se consideran fallos. La resolución DNS está limitada a cinco segundos y la solicitud HTTP a diez segundos.

El historial de envíos muestra las últimas 50 solicitudes, sus intentos, estado y código HTTP. El historial de envíos finalizados se conserva durante 30 días. Un postback fallido no modifica la respuesta de la API entrante ni el estado de envío de conversiones a Meta, TikTok o Snapchat. Evita los bucles: no devuelvas cada postback saliente a AdTarget como un nuevo evento entrante.

Last updated on
Conversions APIOverview