Endpoint-ul de lot rulează până la 20 de texte prin motorul antispam Telm într-un singur POST, returnând un verdict pentru fiecare. Folosește doar reguli (fără nivelul AI) și este disponibil pe planul Pro sau superior. Cota este taxată per element, deci un lot de zece texte consumă zece apeluri. Pentru un singur text cu o verificare AI opțională, folosiți endpoint-ul obișnuit de verificare a spamului.
1Ce face verificarea de spam în lot
Verificarea de spam în lot vă permite să punctați multe texte deodată în loc să faceți o cerere per mesaj. Trimiteți un POST către /spam/check-batch cu o matrice de elemente și primiți înapoi o matrice de verdicte în aceeași ordine — ideal pentru clasificarea unui backlog de mesaje, moderarea unui flux de comentarii sau evaluarea calității detectării pe un eșantion.
Lotul rulează același motor de reguli care protejează grupurile live, dar nu rulează nivelul AI, ceea ce menține fiecare cerere rapidă și previzibilă. Dacă aveți nevoie de verificarea AI, folosiți endpoint-ul individual de verificare a spamului cu opțiunea AI activată, câte un text pe rând.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Punctează până la 20 de texte per cerere, verdictele returnate în ordinea intrării.
- Doar reguli: nivelul AI nu rulează în modul lot.
2Formatul cererii
Corpul cererii este un obiect JSON cu o matrice items. Fiecare element are un câmp text obligatoriu și un obiect context opțional care reflectă ceea ce vede motorul live — group_id-ul, expeditorul user_telegram_id, dacă expeditorul este un utilizator nou, username-ul și indicatori precum allow_sales și crypto_community.
Când un element include un group_id în contextul său, verificarea aplică regulile personalizate și setările acelui grup, deci contul dumneavoastră trebuie să fie administrator al acelui grup, altfel întreaga cerere este respinsă. Omiteți contextul de grup pentru a puncta față de setul de reguli global în schimb.
- Câmp de nivel superior: items — o matrice de la unu la douăzeci de intrări.
- Fiecare element: text (obligatoriu) și un obiect context opțional.
- Contextul poate purta group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Un context de grup necesită să administrați acel grup.
3Formatul răspunsului
Răspunsul este un obiect JSON cu o matrice results — un verdict per element de intrare, în aceeași ordine — și un obiect quota care arată numărul dumneavoastră consumat, limita zilnică și momentul de resetare.
Fiecare verdict vă spune clasificarea și de ce. Câmpul verdict este unul dintre spam, suspicious sau clean. Alături de el primiți un score și un confidence numeric, un recommended_action (unul dintre none, review, warn, mute, kick, ban sau delete), o listă de categories, motive lizibile pentru om, numele matched_rules și o hartă signals cu contribuțiile individuale de punctare.
- results — un verdict per element, în ordinea intrării.
- verdict — spam, suspicious sau clean.
- Fiecare verdict are de asemenea score, confidence, recommended_action, categories, reasons, matched_rules și signals.
- quota — used, limit și reset_at, reflectate în corp.
4Limite și cost de cotă
Un lot este plafonat la 20 de elemente per cerere, iar fiecare text este limitat la 10.000 de caractere. Întregul corp al cererii are de asemenea un plafon de dimensiune, deci cererile foarte mari sunt respinse înainte de procesare. Dacă aveți mai mult de 20 de texte, împărțiți-le pe mai multe cereri.
Cota este taxată per element, nu per cerere: un lot de zece texte consumă zece apeluri din cota dumneavoastră zilnică. Acesta este același buget descris în limitele de rată și cotele API, iar răspunsul poartă anteturile obișnuite X-Quota-Limit, X-Quota-Used și X-Quota-Reset.
- Până la 20 de elemente per cerere; până la 10.000 de caractere per text.
- Costul de cotă egalează numărul de elemente din lot.
- Se aplică anteturile standard X-Quota-*, plus un obiect quota în corp.
5Erori și timeout-uri
Cererile greșite returnează 400 cu un cod specific: o matrice items goală, un lot peste limita de elemente, un text lipsă sau un text peste limita de lungime. Un context de grup pe care nu îl administrați returnează 404 pentru acel element. Un plan sub Pro returnează 403 cu un cod plan_required.
Dacă procesarea unui lot depășește bugetul său de timp, API-ul returnează 504 și rambursează cota pentru elementele pe care nu le-a finalizat, deci sunteți taxat doar pentru munca finalizată. Dacă vedeți timeout-uri, trimiteți loturi mai mici.
- 400 — empty_batch, batch_too_large, missing_text sau text_too_long.
- 404 — un grup din contextul unui element nu este unul pe care îl administrați.
- 403 plan_required — endpoint-ul de lot necesită Pro sau superior.
- 504 timeout — lotul a rulat prea mult; elementele nefinalizate sunt rambursate. Trimiteți mai puține texte.