1Une modération qui dialogue avec le reste de votre stack
Un bot de modération qui vit entièrement à l'intérieur de Telegram est utile, mais c'est aussi une île. Les décisions qu'il prend — chaque message qu'il supprime, chaque utilisateur qu'il filtre, chaque raid qu'il repousse — restent enfermées dans une fenêtre de discussion, à moins que quelqu'un n'ouvre Telegram pour les consulter. Pour une seule communauté, c'est très bien. Pour une équipe qui gère la modération dans le cadre d'une opération plus large, cela signifie que le seul système qui en sait le plus sur ceux qui abusent de vos espaces est aussi le seul qui ne peut communiquer avec rien d'autre de ce que vous faites tourner.
L'API REST publique et les webhooks comblent cet écart. Ils transforment Telm, d'un bot autonome, en un composant que vous pouvez brancher sur les outils que vous avez déjà : votre supervision et votre astreinte, votre archive de conformité, votre propre produit, vos tableaux de bord internes. Le moteur même qui protège vos groupes devient quelque chose que vos autres systèmes peuvent interroger, écouter et piloter.
Ce guide passe en revue ce que l'API et les webhooks exposent réellement — les endpoints, les événements, le modèle de sécurité — et les choses concrètes que les équipes construisent avec. Tout ce qui suit est une capacité réelle, disponible aujourd'hui ; il n'y a aucun SDK à attendre et rien de ce qui est décrit ici ne relève d'un simple projet du produit.
2L'API REST et vos clés
L'API se trouve à `https://api.telm.com/api/public/v1`. C'est une interface REST toute simple — vous l'appelez avec des requêtes HTTPS ordinaires et du JSON, depuis n'importe quel langage, sans bibliothèque cliente particulière. Si votre code sait faire une requête HTTP, il sait dialoguer avec Telm.
L'authentification se fait par clé API. Vous créez vos clés dans le tableau de bord, sous Paramètres → API et Webhooks, et chacune ne vous est montrée qu'une seule fois à la création — copiez-la dans votre coffre à secrets sur-le-champ, car elle ne pourra plus être récupérée ensuite. Les clés sont préfixées `tk_live_` pour être faciles à reconnaître dans les logs et la configuration. Chaque clé porte une portée — lecture ou écriture — de sorte qu'un service qui n'a besoin que de récupérer le journal de décisions peut détenir une clé en lecture seule, tandis qu'une automatisation qui modifie des paramètres reçoit une clé en écriture. Créez une clé par système, et révoquer une clé fuitée ou retirée ne perturbe jamais les autres.
L'usage est encadré par un quota de requêtes quotidien lié à votre plan, si bien que le débit est prévisible et qu'un script emballé ne peut tout épuiser. La vérification la plus légère — l'analyse anti-spam de texte — est disponible sur tous les plans dans la limite de ce quota ; la surface plus étendue, du journal de décisions à la gestion des paramètres en passant par les webhooks, fait partie des plans Pro et Business. Les chiffres exacts sont détaillés à la fin.
3Filtrer textes et utilisateurs à la demande
Deux endpoints vous permettent d'exécuter le jugement de Telm à la demande, depuis votre propre code, sans qu'aucun message ne passe jamais par un groupe Telegram.
`POST /spam/check` envoie un morceau de texte dans le moteur de production exact qui protège vos communautés — les signaux partagés sur les spammeurs, les règles de motifs, les classificateurs — et renvoie un verdict. C'est l'appel disponible sur tous les plans, ce qui en fait un filtre anti-spam naturel pour votre propre produit : filtrez commentaires, bios d'inscription, tickets de support ou annonces de marketplace avec la détection même qui protège vos espaces Telegram. Ajoutez `include_ai` pour intégrer un verdict d'IA sur les cas plus difficiles et ambigus (disponible sur Pro et Business), et sur ces plans vous pouvez grouper jusqu'à vingt textes en une seule requête plutôt que d'appeler une fois par élément.
`POST /users/check` filtre une personne plutôt qu'un message. Il combine la liste de blocage globale CAS et le jeu de données propre à Telm, bâti à partir de la modération de nombreuses communautés, et renvoie un niveau de risque (sur Pro et Business) pour que vous décidiez du degré de friction à appliquer — laissez passer directement un compte propre, retenez pour examen un compte à risque. Le brancher sur votre propre parcours d'inscription vous permet d'attraper un acteur malveillant connu dès la porte de votre site ou de votre application, et pas seulement après qu'il a rejoint un groupe Telegram.
Les deux appels répondent en ligne : vous envoyez le texte ou l'utilisateur, vous obtenez l'évaluation dans la réponse. Aucune file à interroger, aucun rappel à attendre — la décision arrive avec la réponse.
4Se faire pousser l'information à l'instant où elle survient
Interroger le journal convient à l'archivage, mais quand vous voulez *réagir* à quelque chose à l'instant même où cela se produit, mieux vaut qu'on vous le pousse plutôt que de le demander. Les webhooks (sur Pro et Business) font exactement cela : vous enregistrez un endpoint, et Telm lui envoie une requête HTTP à l'instant où un événement pertinent se déclenche. Les événements couvrent les moments qui comptent — `spam.detected` et `message.suspicious` pour le contenu, et `user.banned`, `user.kicked`, `user.muted`, `user.joined` et `user.left` pour l'appartenance.
L'usage évident consiste à transformer une vague de spam en alerte. Pointez `spam.detected` vers votre système de supervision ou d'astreinte et une montée soudaine devient une alerte pour la personne de garde, au même endroit que vos autres incidents — plus besoin de surveiller Telegram pour repérer le début d'une attaque. Le même flux alimente des tableaux de bord en temps réel, maintient un système externe synchronisé avec les bannissements ou déclenche n'importe quel workflow de votre choix.
Parce que ces requêtes viennent du monde extérieur vers votre infrastructure, chaque livraison est signée. Chaque requête porte un en-tête `X-Telm-Signature` de la forme `v1=hex(hmac_sha256(secret, "timestamp.body"))` — un HMAC-SHA256 sur l'horodatage et le corps brut, avec pour clé un secret que vous seul et Telm partagez. Recalculer cette signature de votre côté prouve que la requête vient réellement de Telm et n'a été ni falsifiée ni altérée en transit ; l'horodatage vous permet de rejeter les rejeux (replays) périmés. Vérifiez la signature avant de faire confiance à la charge utile — c'est quelques lignes de code et l'étape la plus importante d'un récepteur de webhook sûr.
5Une livraison sur laquelle vous pouvez compter
Un modèle « push » n'est fiable que s'il gère les moments où votre endpoint est lent, redémarre ou brièvement en panne — et c'est le cas de celui de Telm. La livraison se fait au moins une fois : chaque événement porte un `id` stable, et Telm continue d'essayer jusqu'à ce que votre endpoint l'accuse réception. Comme « au moins une fois » signifie qu'un même événement peut légitimement arriver deux fois, dédupliquez sur cet `id` — enregistrez ceux que vous avez traités et ignorez les répétitions — et votre traitement reste correct quel que soit le nombre de relances d'une livraison.
Les relances suivent un calendrier qui s'élargit plutôt que de marteler un endpoint en difficulté : immédiatement, puis après une minute, cinq minutes, trente minutes, deux heures et six heures — six tentatives en tout, espacées pour laisser à un service en cours de rétablissement le temps de revenir. Si un endpoint reste défaillant — vingt échecs consécutifs et soixante-douze heures sans livraison réussie — Telm cesse automatiquement de lui envoyer quoi que ce soit et vous prévient sur Telegram, de sorte qu'une URL morte devient un avertissement clair pour réparer votre récepteur plutôt qu'un déluge silencieux d'échecs qui s'accumulent.
Pour réussir une nouvelle intégration, vous n'avez pas à provoquer de vrais événements pour la tester. Un ping de test vous permet d'envoyer une livraison d'exemple à votre endpoint à la demande et de confirmer que votre vérification de signature et votre gestionnaire fonctionnent, et un historique de livraison montre ce qui a été envoyé et comment chaque tentative s'est déroulée — pour que vous puissiez déboguer un récepteur récalcitrant à partir du registre plutôt qu'en devinant.
6Un registre interrogeable de chaque décision
Tout ce que le moteur décide est enregistré, et `GET journal` remet ce registre à votre code. Chaque entrée est une décision : le verdict, le score qui le sous-tend, les règles qui se sont déclenchées et l'action qui a suivi. Comme la pagination se fait par curseur, vous pouvez parcourir l'historique complet de façon fiable — page après page, sans trous ni doublons — et le rapatrier là où vous conservez vos archives.
C'est ce qui fait du journal l'ossature d'une archive de conformité. Les équipes qui doivent justifier le retrait d'un membre — pour une politique de plateforme, un contrat client ou un régulateur — exportent le journal vers leur propre stockage à long terme selon un calendrier, ce qui leur donne un compte rendu indépendant et interrogeable de chaque action d'application, sans dépendre d'un défilement en arrière dans Telegram. Ce sont les mêmes preuves que le journal d'audit du tableau de bord présente aux humains, rendues accessibles à vos systèmes.
À ses côtés, un endpoint d'analytique renvoie des séries jour par jour — volumes et tendances dans le temps — pour que vous puissiez tracer la charge de modération dans vos propres outils de business intelligence, aux côtés de tout ce que vous suivez déjà, plutôt que de la lire sur un écran. Le journal comme l'analytique font partie des plans Pro et Business.
7Gérer de nombreux groupes depuis le code
L'API ne fait pas que lire et écouter — elle écrit. Sur Pro et Business, vous pouvez modifier les paramètres d'un groupe avec `PATCH` et exécuter les opérations complètes de création/lecture/mise à jour/suppression sur ses règles et sa liste blanche, le tout par programmation. Tout ce que vous configureriez à la main dans le tableau de bord, vous pouvez le configurer depuis un script.
C'est ce qui rend la modération à grande échelle praticable. Une agence ou un gros opérateur qui gère des dizaines de communautés ne veut pas ouvrir chacune et cliquer à travers les mêmes changements ; il veut définir la politique une fois et l'appliquer partout. Avec l'API, vous déployez une nouvelle règle, ajustez un seuil ou ajoutez une adresse à chaque liste blanche de toute la flotte en une seule passe automatisée, et vous gardez les groupes au diapason à mesure que vos standards évoluent.
Cela permet aussi à la politique de modération de vivre dans votre propre gestion de versions. Conservez la configuration souhaitée sous forme de code, appliquez-la via l'API, et chaque changement dans la gouvernance de vos groupes est revu et versionné comme le reste de votre infrastructure — à mille lieues de devoir se souvenir des paramètres que vous avez basculés dans tel ou tel salon.
8Ce que chaque plan inclut
La ligne de partage est simple. La vérification anti-spam de texte est disponible sur tous les plans, si bien que même l'offre gratuite peut utiliser la détection de Telm comme filtre dans son propre produit. La surface complète — filtrage des utilisateurs avec niveaux de risque, journal de décisions et analytique, gestion des paramètres et des règles, et webhooks — fait partie des plans Pro et Business.
Chaque plan reçoit un quota de requêtes quotidien, calibré pour que les intégrations plus lourdes reposent sur des plans plus lourds :
- **Free** — 100 requêtes API par jour, vérification anti-spam uniquement.
- **Basic** — 1 000 requêtes API par jour, vérification anti-spam uniquement.
- **Pro** — 10 000 requêtes API par jour, plus la surface API complète et les webhooks.
- **Business** — 50 000 requêtes API par jour, plus la surface API complète et les webhooks.
- Créez vos clés sous Paramètres → API et Webhooks, conservez-les dans votre coffre à secrets, vérifiez la signature de chaque webhook, et le moteur même qui protège vos groupes devient une partie de votre propre stack.