L’endpoint in batch fa passare fino a 20 testi attraverso il motore antispam di Telm in un unico POST, restituendo un verdetto per ciascuno. È basato solo su regole (nessun livello AI) e disponibile sul piano Pro e superiori. La quota è addebitata per elemento, quindi un batch di dieci testi spende dieci chiamate. Per un singolo testo con un controllo AI facoltativo, usi l’endpoint di controllo spam normale.
1Cosa fa il controllo spam in batch
Il controllo spam in batch Le consente di valutare molti testi in una volta invece di fare una richiesta per messaggio. Invia un POST a /spam/check-batch con un array di elementi e riceve indietro un array di verdetti nello stesso ordine — ideale per classificare un arretrato di messaggi, moderare un flusso di commenti o valutare la qualità del rilevamento su un campione.
Il batch esegue lo stesso motore di regole che protegge i gruppi dal vivo, ma non esegue il livello AI, il che mantiene ogni richiesta veloce e prevedibile. Se Le serve il controllo AI, usi l’endpoint di controllo spam singolo con l’opzione AI abilitata, un testo alla volta.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Valuta fino a 20 testi per richiesta, verdetti restituiti nell’ordine di input.
- Solo regole: il livello AI non viene eseguito in modalità batch.
2Formato della richiesta
Il corpo della richiesta è un oggetto JSON con un array items. Ogni elemento ha un campo text obbligatorio e un oggetto context facoltativo che rispecchia ciò che vede il motore dal vivo — il group_id, il user_telegram_id del mittente, se il mittente è un nuovo utente, lo username e flag come allow_sales e crypto_community.
Quando un elemento include un group_id nel suo context, il controllo applica le regole personalizzate e le impostazioni di quel gruppo, quindi il Suo account deve essere amministratore di quel gruppo o l’intera richiesta viene rifiutata. Ometta il context del gruppo per valutare sul set di regole globale.
- Campo di primo livello: items — un array da uno a venti voci.
- Ogni elemento: text (obbligatorio) e un oggetto context facoltativo.
- Il context può trasportare group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Un context di gruppo richiede che Lei amministri quel gruppo.
3Formato della risposta
La risposta è un oggetto JSON con un array results — un verdetto per elemento di input, nello stesso ordine — e un oggetto quota che mostra il Suo conteggio usato, il limite giornaliero e l’orario di azzeramento.
Ogni verdetto Le dice la classificazione e il perché. Il campo verdict è uno tra spam, suspicious o clean. Insieme ad esso ottiene un score e una confidence numerici, una recommended_action (una tra none, review, warn, mute, kick, ban o delete), un elenco di categories, reasons leggibili dall’uomo, i nomi delle matched_rules e una mappa signals con i singoli contributi al punteggio.
- results — un verdetto per elemento, nell’ordine di input.
- verdict — spam, suspicious o clean.
- Ogni verdetto ha anche score, confidence, recommended_action, categories, reasons, matched_rules e signals.
- quota — used, limit e reset_at, riportati nel corpo.
4Limiti e costo della quota
Un batch è limitato a 20 elementi per richiesta, e ogni testo è limitato a 10.000 caratteri. L’intero corpo della richiesta ha anch’esso un tetto di dimensione, quindi payload molto grandi vengono rifiutati prima dell’elaborazione. Se ha più di 20 testi, li suddivida su più richieste.
La quota è addebitata per elemento, non per richiesta: un batch di dieci testi spende dieci chiamate dalla Sua quota giornaliera. Questo è lo stesso budget descritto in limiti di frequenza e quote API, e la risposta trasporta i consueti header X-Quota-Limit, X-Quota-Used e X-Quota-Reset.
- Fino a 20 elementi per richiesta; fino a 10.000 caratteri per testo.
- Il costo della quota è pari al numero di elementi nel batch.
- Si applicano gli header standard X-Quota-*, più un oggetto quota nel corpo.
5Errori e timeout
Le richieste non valide restituiscono 400 con un codice specifico: un array items vuoto, un batch oltre il limite di elementi, un text mancante o un text oltre il limite di lunghezza. Un context di gruppo che non amministra restituisce 404 per quell’elemento. Un piano inferiore a Pro restituisce 403 con un codice plan_required.
Se l’elaborazione di un batch supera il suo budget di tempo, l’API restituisce 504 e rimborsa la quota per gli elementi che non ha terminato, così Le viene addebitato solo il lavoro completato. Se vede timeout, invii batch più piccoli.
- 400 — empty_batch, batch_too_large, missing_text o text_too_long.
- 404 — un gruppo nel context di un elemento non è uno che amministra.
- 403 plan_required — l’endpoint in batch richiede Pro o superiore.
- 504 timeout — il batch è durato troppo a lungo; gli elementi non terminati vengono rimborsati. Invii meno testi.