API REST — automatisez Telm depuis votre propre code

1Ce que l’API vous permet de faire

L’API REST Telm donne à votre propre code la même portée que le tableau de bord : faire passer n’importe quel texte dans la chaîne anti-spam, consulter un utilisateur Telegram avant de le laisser entrer, lire et modifier les paramètres de protection d’un groupe, gérer les règles personnalisées et les listes blanches, récupérer le journal de modération et l’analytique, et enregistrer des webhooks pour les événements en temps réel.

Telm n’est alors plus seulement un bot qui vit dans vos groupes, mais une infrastructure que vous pouvez brancher n’importe où — un formulaire d’inscription sur un site, un bot de CRM, vos propres bots Telegram, ou un script qui configure cent groupes d’un coup.

• URL de base : api.telm.com/api/public/v1 — un chemin stable et versionné (le v1 est la version du contrat).
• Chaque requête et chaque réponse sont en JSON sur HTTPS.
• La documentation interactive et la spécification OpenAPI 3.1 lisible par machine se trouvent sur la page développeurs — chargez la spécification dans Postman, un générateur de code ou un agent IA pour monter une intégration en quelques minutes.
• Les appels mesurés renvoient les en-têtes X-Quota-Limit, X-Quota-Used et X-Quota-Reset sur chaque réponse.

2Le parcours d’une requête dans Telm

L’API publique a son propre préfixe de chemin, /api/public/, séparé du tableau de bord. Chaque appel est authentifié par une clé API plutôt que par une session de navigateur, contrôlé par rapport à votre forfait et à votre quota, exécuté sur le même moteur en direct qui modère vos groupes, puis renvoyé en JSON.

Comme l’API atteint le même moteur et les mêmes données que le bot, tout ce que vous pouvez voir ou modifier dans le tableau de bord, vous pouvez aussi le faire dans le code — et toute modification faite dans le code apparaît immédiatement dans le tableau de bord.

• Les requêtes sont sans état : chacune porte sa propre clé et se suffit à elle-même.
• Une clé agit au nom de votre compte et ne peut toucher que les groupes où votre compte est administrateur.
• L’endpoint de vérification anti-spam atteint exactement la chaîne de règles de production, si bien qu’un verdict de l’API correspond à ce que ferait le bot dans le groupe.

3L’authentification par clés API

Chaque requête est authentifiée par une clé API de la forme tk_live_ suivi de caractères aléatoires — pas par votre identifiant de tableau de bord. Vous créez les clés dans votre compte et envoyez la clé dans l’en-tête Authorization comme jeton Bearer, ou dans un en-tête X-API-Key.

Le secret complet n’est affiché qu’une seule fois, au moment de la création. Ensuite, le tableau de bord ne liste une clé que par son court préfixe, afin que vous puissiez la reconnaître sans jamais conserver la valeur complète. Si une clé fuit, révoquez-la et émettez-en une nouvelle — la révocation prend effet immédiatement.

• Envoyez la clé sous la forme Authorization: Bearer tk_live_your_key_here (un en-tête X-API-Key fonctionne aussi).
• Les clés ont une portée lecture ou écriture — lecture pour les requêtes GET, écriture pour tout ce qui modifie des données. Une clé en lecture seule ne peut ni créer ni modifier.
• Vous pouvez détenir jusqu’à dix clés actives à la fois, ce qui permet d’utiliser une clé distincte par script ou service.
• Une clé manquante ou invalide renvoie 401 ; une clé sans la portée requise renvoie 403 insufficient_scope.

4Les endpoints disponibles

L’API s’organise autour des vérifications de spam et d’utilisateurs, de la gestion des groupes et de la gestion autonome du compte. L’endpoint de vérification anti-spam simple est ouvert à tous les forfaits ; le reste de l’API fait partie de Pro et Business.

• POST /spam/check — fait passer un texte dans le même moteur de règles qui modère le trafic en direct (tous les forfaits). Une vérification IA facultative peut être activée sur Pro et au-delà.
• POST /spam/check-batch — vérifie jusqu’à 20 textes en un seul appel, règles seules (Pro+).
• POST /users/check — consulte un utilisateur Telegram : statut CAS, signaux des décisions anti-spam de Telm et réputation dans vos groupes (Pro+).
• GET /groups et GET /groups/{id} — listent et lisent vos groupes (Pro+).
• GET et PATCH /groups/{id}/settings — lisent et modifient les paramètres de protection d’un groupe (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — gèrent les règles de modération personnalisées (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — gèrent la liste blanche du groupe (Pro+).
• GET /groups/{id}/journal et GET /groups/{id}/analytics — lisent le journal de modération et l’analytique (Pro+).
• GET/POST/PATCH/DELETE /webhooks — gèrent les webhooks d’événements en temps réel (Pro+).
• GET /usage et GET /me — consultent votre quota et les informations de la clé ; ils ne consomment jamais de quota (tous les forfaits).

5L’endpoint de vérification anti-spam en détail

POST /spam/check est le cœur de l’API et le seul endpoint que vous pouvez essayer sur n’importe quel forfait. Envoyez un corps JSON avec le texte à vérifier ; la réponse renvoie un verdict, un score numérique, une valeur de confiance et une action recommandée que vous pouvez appliquer dans votre propre produit.

Un même texte peut compter jusqu’à 10 000 caractères. Sur Pro et au-delà, vous pouvez activer une vérification IA pour les cas plus difficiles, puisée dans une allocation quotidienne de vérifications IA distincte. Pour les gros volumes, l’endpoint par lot vérifie jusqu’à 20 textes en un seul appel et compte le quota par élément.

• Utilisez le verdict et le score pour décider de ce que fait votre propre produit — bloquer l’envoi d’un formulaire, signaler un prospect ou supprimer automatiquement un message dans votre propre bot.
• L’endpoint par lot est fondé sur les règles seules ; l’échelle IA n’est disponible que sur l’endpoint à texte unique.
• La taille des corps de requête est plafonnée (environ 64 Ko pour une vérification simple, 256 Ko pour un lot) ; les corps trop volumineux renvoient 413.

6Forfaits, limites de débit et quotas quotidiens

L’accès est mesuré de deux façons : une limite de débit par minute (un plafond de rafale) et un quota d’appels quotidien qui se réinitialise à minuit UTC. Les deux sont comptés par compte et partagés entre toutes vos clés API. Vous pouvez essayer l’endpoint de vérification anti-spam simple sur n’importe quel forfait, mais une véritable intégration qui touche aux règles, aux paramètres, aux vérifications par lot et aux webhooks nécessite Pro ou supérieur.

• Free — 100 appels par jour, vérification anti-spam uniquement.
• Pro — 10 000 appels par jour, API complète et webhooks, plus 1 000 vérifications IA par jour.
• Business — 50 000 appels par jour, API complète et webhooks, plus 10 000 vérifications IA par jour.
• Les limites de débit par minute augmentent aussi — 60 requêtes par minute sur Free, 600 sur Pro et 1 800 sur Business.
• GET /usage et GET /me ne sont jamais décomptés de votre quota, si bien que vous pouvez consulter votre budget restant à tout moment.

7Gestion des erreurs et codes de statut

L’API utilise les codes de statut HTTP standard avec un code d’erreur lisible par machine dans le corps. Concevez votre client pour lire ces codes et temporiser ou proposer une mise à niveau, plutôt que de réessayer à l’aveugle.

Quand vous dépassez votre quota quotidien, un appel mesuré renvoie 429 avec un code daily_quota_exceeded, un en-tête Retry-After et un corps indiquant votre forfait, votre limite, le nombre d’appels utilisés, l’heure de réinitialisation et une suggestion de mise à niveau. Les endpoints qui exigent un forfait supérieur renvoient 403 plan_required avec le forfait requis.

• 401 — clé API manquante ou invalide.
• 403 plan_required — l’endpoint nécessite Pro ou supérieur.
• 403 insufficient_scope — la clé n’a pas la portée écriture requise pour un appel qui modifie des données.
• 429 daily_quota_exceeded ou rate_limit_exceeded — attendez l’heure de réinitialisation ou passez à un forfait supérieur ; respectez l’en-tête Retry-After.
• Lisez les en-têtes de réponse X-Quota-* pour garder une longueur d’avance sur la limite.

8Bonnes pratiques pour une intégration solide

Quelques habitudes gardent une intégration fiable et sûre à mesure qu’elle grandit.

• Stockez les clés dans un gestionnaire de secrets, jamais dans du code côté client ni dans un dépôt git ; utilisez une clé distincte par service pour pouvoir en révoquer une sans casser les autres.
• Surveillez les en-têtes X-Quota-Used et X-Quota-Limit (ou interrogez GET /usage) et ralentissez avant d’atteindre la limite, pas après.
• Sur un 429, respectez Retry-After et temporisez ; sur un 403 plan_required, affichez une invitation à passer à un forfait supérieur plutôt que de réessayer.
• Pour réagir en temps réel, préférez les webhooks à l’interrogation régulière — laissez Telm vous pousser les événements.
• Faites tourner les clés régulièrement, et immédiatement si l’une d’elles a pu fuiter.

9Scénarios d’intégration courants

L’API sert à bien plus qu’à modérer des messages Telegram.

• Inscription sur un site ou une application : faites passer le texte soumis ou les noms d’utilisateur par POST /spam/check avant d’accepter une inscription ou un commentaire.
• Vos propres bots Telegram : réutilisez l’intelligence de Telm dans un bot que Telm ne gère pas, en appelant l’endpoint de vérification depuis votre gestionnaire.
• Configuration en masse : appliquez par script les mêmes règles, listes blanches et paramètres à des dizaines de groupes grâce aux endpoints des paramètres et des règles.
• Données et alertes : enregistrez des webhooks pour diffuser en temps réel les événements de modération vers un entrepôt de données, un tableau de bord ou un canal d’alerte.