L’endpoint par lot fait passer jusqu’à 20 textes à travers le moteur anti-spam de Telm en un seul POST, renvoyant un verdict pour chacun. Il est fondé sur les règles seules (pas de niveau IA) et disponible sur le plan Pro et au-delà. Le quota est facturé par élément, si bien qu’un lot de dix textes dépense dix appels. Pour un seul texte avec une vérification IA optionnelle, utilisez l’endpoint de vérification anti-spam ordinaire.
1Ce que fait la vérification anti-spam par lot
La vérification anti-spam par lot vous permet d’évaluer de nombreux textes à la fois au lieu de faire une requête par message. Vous envoyez un POST à /spam/check-batch avec un tableau d’éléments et récupérez un tableau de verdicts dans le même ordre — idéal pour classer un arriéré de messages, modérer un fil de commentaires, ou évaluer la qualité de détection sur un échantillon.
Le lot fait tourner le même moteur de règles qui protège les groupes en direct, mais il n’exécute pas le niveau IA, ce qui garde chaque requête rapide et prévisible. Si vous avez besoin de la vérification IA, utilisez l’endpoint de vérification anti-spam simple avec l’option IA activée, un texte à la fois.
- Endpoint : POST /api/public/v1/spam/check-batch.
- Évalue jusqu’à 20 textes par requête, verdicts renvoyés dans l’ordre d’entrée.
- Règles seules : le niveau IA n’est pas exécuté en mode par lot.
2Format de la requête
Le corps de la requête est un objet JSON avec un tableau items. Chaque élément a un champ text requis et un objet context optionnel qui reflète ce que voit le moteur en direct — le group_id, le user_telegram_id de l’expéditeur, si l’expéditeur est un nouvel utilisateur, le username, et des drapeaux comme allow_sales et crypto_community.
Quand un élément inclut un group_id dans son context, la vérification applique les règles personnalisées et les paramètres de ce groupe, votre compte doit donc être administrateur de ce groupe ou toute la requête est rejetée. Omettez le contexte de groupe pour évaluer plutôt au regard de l’ensemble de règles mondial.
- Champ de premier niveau : items — un tableau d’une à vingt entrées.
- Chaque élément : text (requis) et un objet context optionnel.
- Le contexte peut porter group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Un contexte de groupe exige que vous administriez ce groupe.
3Format de la réponse
La réponse est un objet JSON avec un tableau results — un verdict par élément d’entrée, dans le même ordre — et un objet quota montrant votre nombre d’appels utilisés, votre limite quotidienne et l’heure de réinitialisation.
Chaque verdict vous indique la classification et pourquoi. Le champ verdict est l’un de spam, suspicious ou clean. À côté, vous obtenez un score numérique et une confidence, une recommended_action (l’une de none, review, warn, mute, kick, ban ou delete), une liste de categories, des reasons lisibles par un humain, les noms des matched_rules, et une carte signals avec les contributions de score individuelles.
- results — un verdict par élément, dans l’ordre d’entrée.
- verdict — spam, suspicious ou clean.
- Chaque verdict a aussi score, confidence, recommended_action, categories, reasons, matched_rules et signals.
- quota — used, limit et reset_at, renvoyés dans le corps.
4Limites et coût en quota
Un lot est plafonné à 20 éléments par requête, et chaque texte est limité à 10 000 caractères. Le corps de requête entier a aussi un plafond de taille, si bien que les charges utiles très volumineuses sont rejetées avant traitement. Si vous avez plus de 20 textes, répartissez-les sur plusieurs requêtes.
Le quota est facturé par élément, pas par requête : un lot de dix textes dépense dix appels de votre quota quotidien. C’est le même budget décrit dans Limites de débit et quotas de l’API, et la réponse porte les habituels en-têtes X-Quota-Limit, X-Quota-Used et X-Quota-Reset.
- Jusqu’à 20 éléments par requête ; jusqu’à 10 000 caractères par texte.
- Le coût en quota est égal au nombre d’éléments du lot.
- Les en-têtes X-Quota-* standard s’appliquent, plus un objet quota dans le corps.
5Erreurs et dépassements de délai
Les requêtes incorrectes renvoient 400 avec un code précis : un tableau items vide, un lot au-dessus de la limite d’éléments, un text manquant, ou un text au-dessus de la limite de longueur. Un contexte de groupe que vous n’administrez pas renvoie 404 pour cet élément. Un plan en dessous de Pro renvoie 403 avec un code plan_required.
Si le traitement d’un lot dépasse son budget de temps, l’API renvoie 504 et rembourse le quota des éléments qu’elle n’a pas terminés, si bien que vous n’êtes facturé que pour le travail achevé. Si vous voyez des dépassements de délai, envoyez des lots plus petits.
- 400 — empty_batch, batch_too_large, missing_text ou text_too_long.
- 404 — un groupe dans un contexte d’élément n’en est pas un que vous administrez.
- 403 plan_required — l’endpoint par lot nécessite Pro ou supérieur.
- 504 timeout — le lot a duré trop longtemps ; les éléments inachevés sont remboursés. Envoyez moins de textes.