Skip to Content
Suivez vos conversions Telegram avec Meta Ads — commencez en quelques minutes !
Référence APIPostbacks

Postbacks sortants

Les postbacks transmettent les nouveaux événements de conversion AdTarget à votre serveur. Ils sont distincts de l’API REST entrante : les clés API, les requêtes, l’attribution et les envois aux plateformes publicitaires existants continuent de fonctionner.

Événements Telegram

La première section transmet les mises à jour Telegram brutes, et non des conversions publicitaires. Choisissez une destination et sélectionnez business_message (messages privés Business), business_connection, chat_join_request et/ou chat_member (adhésions, départs et changements de statut).

La configuration s’applique à un bot à l’échelle du compte, et pas uniquement à un site web. La destination reçoit le contenu des messages et les identités Telegram présents dans les mises à jour sélectionnées. Configurez uniquement un backend que vous contrôlez. L’historique des envois est rattaché au site sur lequel la destination a été configurée initialement.

Les nouveaux relais génériques envoient un corps JSON contenant update_id et l’objet de mise à jour Telegram sélectionné, sans modification. Ils utilisent les en-têtes de signature et de livraison X-AdTarget-* décrits ci-dessous, une file d’attente persistante et jusqu’à six tentatives. Les identifiants de mise à jour Telegram répétés sont dédupliqués dans la limite de l’historique des envois conservé. Ces relais ne créent aucun événement Lead, Purchase ou autre événement publicitaire.

Intégration TSA / Ross existante

Le relais TSA existant est affiché avec son URL actuelle et les types Telegram activés. Il conserve sa destination /telegram/proxy, l’authentification X-Forward-Secret / X-Forward-Timestamp, le contenu Telegram brut enrichi d’informations de provenance et sa politique de nouvelles tentatives existante. Il n’utilise pas le protocole HMAC générique ni les nouveaux interrupteurs de conversion. Il reste le seul émetteur pour TSAWelcomeBot : aucun second émetteur automatique, changement de secret, renvoi de l’historique ou migration du destinataire n’est effectué. Ses envois antérieurs ne sont pas ajoutés rétroactivement à l’historique des envois génériques.

Cette intégration existante protégée est en lecture seule dans cet éditeur. L’activation de nouveaux relais pour d’autres bots ne la remplace pas.

Événements de conversion (facultatif)

Développez Événements de conversion — facultatif pour transmettre les nouvelles conversions enregistrées dans AdTarget, y compris celles reçues via l’API REST entrante. Ces interrupteurs ne contrôlent pas le relais Telegram décrit ci-dessus.

Configurer l’envoi des conversions

Ouvrez Site → Réglages → Postbacks, saisissez une URL HTTPS publique, sélectionnez les types d’événements et activez les envois. Enregistrez, copiez le secret de signature affiché une seule fois, puis choisissez Envoyer un test. La file d’attente commence normalement les envois sous une minute. Seul le propriétaire du site peut modifier la configuration ; l’aperçu administrateur est en lecture seule.

Types pris en charge : Lead, Purchase, CompleteRegistration, Subscribe, Contact et Custom. Sélectionner Custom inclut tous les noms personnalisés ; utilisez data.customEventName pour les distinguer. Il s’agit de types de conversion, et non de pages vues, d’adhésions ou de départs Telegram bruts, ni d’étapes métier dérivées telles que QFTD. Une adhésion utilise l’événement de conversion configuré pour le canal concerné.

Seules les nouvelles conversions créées après l’activation sont envoyées. L’historique existant, les modifications de valeur ultérieures et les conversions déjà existantes réutilisées par l’API entrante ne sont pas renvoyés. Aucune migration de l’historique n’est nécessaire. Les événements sans site identifié ne peuvent pas être envoyés à l’endpoint d’un site.

L’enregistrement des réglages annule les envois en attente de la configuration précédente. La désactivation arrête les envois en file d’attente ; une requête déjà en cours peut se terminer. Utilisez un nom d’hôte public résolu en IPv4, avec HTTPS sur le port 443. Les adresses privées et les redirections sont bloquées.

Requête

AdTarget envoie une requête POST avec 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 est un horodatage Unix en millisecondes. Les champs facultatifs sont omis lorsqu’ils sont absents. Les noms, adresses e-mail, numéros de téléphone, adresses IP, clés API et identifiants publicitaires ne sont pas inclus. Un test utilise event: "test" et un exemple de message ; il ne crée aucune conversion et n’envoie rien à vos pixels publicitaires.

Vérifier l’authenticité

Conservez le secret sur votre serveur. Vérifiez les en-têtes suivants :

  • X-AdTarget-Delivery-Id : identifiant stable entre les tentatives ; utilisez-le pour dédupliquer le traitement.
  • X-AdTarget-Timestamp : horodatage Unix en secondes, renouvelé à chaque tentative.
  • X-AdTarget-Signature : sha256= suivi du HMAC-SHA256 hexadécimal de timestamp + "." + rawRequestBody, signé avec votre secret.

Vérifiez la signature sur les octets du corps original avant le décodage JSON, rejetez les horodatages en dehors d’une fenêtre de cinq minutes et comparez les signatures en temps constant. Enregistrez l’identifiant de livraison de manière atomique avec votre opération métier, afin qu’une nouvelle tentative ne puisse pas la répéter. Renvoyez un statut 2xx après avoir accepté la requête de façon persistante.

Fiabilité

La livraison suit un modèle « au moins une fois », et non « exactement une fois ». Un délai d’attente dépassé après l’acceptation d’un événement par votre serveur peut entraîner un doublon. Chaque envoi fait l’objet d’au plus six tentatives au total, avec des délais croissants. Les redirections HTTP et les autres réponses hors 2xx sont considérées comme des échecs. La résolution DNS est limitée à cinq secondes et la requête HTTP à dix secondes.

L’historique des envois affiche les 50 dernières requêtes, leurs tentatives, leur statut et leur code HTTP. L’historique des envois terminés est conservé pendant 30 jours. L’échec d’un postback ne modifie ni la réponse de l’API entrante ni le statut d’envoi des conversions à Meta, TikTok ou Snapchat. Évitez les boucles : ne renvoyez pas chaque postback sortant à AdTarget comme un nouvel événement entrant.

Last updated on
Conversions APIOverview