Dávkový koncový bod propustí až 20 textů antispamovým enginem Telm v jediném POST a vrátí verdikt pro každý z nich. Je pouze pravidlový (žádná úroveň AI) a dostupný na tarifu Pro a vyšším. Kvóta se účtuje na položku, takže dávka deseti textů spotřebuje deset volání. Pro jediný text s volitelnou AI kontrolou použijte běžný koncový bod kontroly spamu.
1Co dávková kontrola spamu dělá
Dávková kontrola spamu vám umožní obodovat mnoho textů najednou místo jednoho požadavku na zprávu. Odešlete POST na /spam/check-batch s polem položek a získáte zpět pole verdiktů ve stejném pořadí — ideální pro klasifikaci nevyřízených zpráv, moderaci proudu komentářů nebo vyhodnocení kvality detekce na vzorku.
Dávka spouští stejný pravidlový engine, který chrání živé skupiny, ale nespouští úroveň AI, což udržuje každý požadavek rychlý a předvídatelný. Pokud potřebujete AI kontrolu, použijte jediný koncový bod kontroly spamu se zapnutou možností AI, po jednom textu.
- Koncový bod: POST /api/public/v1/spam/check-batch.
- Boduje až 20 textů na požadavek, verdikty vrácené v pořadí vstupu.
- Pouze pravidlový: úroveň AI se v dávkovém režimu nespouští.
2Formát požadavku
Tělo požadavku je JSON objekt s polem items. Každá položka má povinné pole text a volitelný objekt context, který zrcadlí to, co vidí živý engine — group_id, odesílatelovo user_telegram_id, zda je odesílatel nový uživatel, username a příznaky jako allow_sales a crypto_community.
Když položka obsahuje ve svém kontextu group_id, kontrola uplatní vlastní pravidla a nastavení dané skupiny, takže váš účet musí být správcem té skupiny, jinak je celý požadavek zamítnut. Vynechte kontext skupiny, abyste bodovali proti globální sadě pravidel.
- Pole na nejvyšší úrovni: items — pole jedné až dvaceti položek.
- Každá položka: text (povinné) a volitelný objekt context.
- Kontext může nést group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Kontext skupiny vyžaduje, abyste tuto skupinu spravovali.
3Formát odpovědi
Odpověď je JSON objekt s polem results — jeden verdikt na vstupní položku, ve stejném pořadí — a objektem quota ukazujícím váš spotřebovaný počet, denní limit a čas resetu.
Každý verdikt vám řekne klasifikaci a proč. Pole verdict je jedno ze spam, suspicious nebo clean. Vedle něj získáte číselné score a confidence, recommended_action (jedno z none, review, warn, mute, kick, ban nebo delete), seznam categories, lidsky čitelné reasons, názvy shodných matched_rules a mapu signals s jednotlivými bodovacími příspěvky.
- results — jeden verdikt na položku, v pořadí vstupu.
- verdict — spam, suspicious nebo clean.
- Každý verdikt má také score, confidence, recommended_action, categories, reasons, matched_rules a signals.
- quota — used, limit a reset_at, odražené v těle.
4Limity a spotřeba kvóty
Dávka je omezena na 20 položek na požadavek a každý text je omezen na 10 000 znaků. Celé tělo požadavku má také strop velikosti, takže velmi velké payloady jsou zamítnuty před zpracováním. Pokud máte více než 20 textů, rozdělte je do několika požadavků.
Kvóta se účtuje na položku, nikoli na požadavek: dávka deseti textů spotřebuje deset volání z vaší denní kvóty. Je to stejný rozpočet popsaný v limitech a kvótách API a odpověď nese obvyklé hlavičky X-Quota-Limit, X-Quota-Used a X-Quota-Reset.
- Až 20 položek na požadavek; až 10 000 znaků na text.
- Spotřeba kvóty se rovná počtu položek v dávce.
- Platí standardní hlavičky X-Quota-*, plus objekt quota v těle.
5Chyby a timeouty
Chybné požadavky vracejí 400 s konkrétním kódem: prázdné pole items, dávka nad limit položek, chybějící text nebo text nad limit délky. Kontext skupiny, kterou nespravujete, vrací pro danou položku 404. Tarif pod Pro vrací 403 s kódem plan_required.
Pokud zpracování dávky překročí svůj časový rozpočet, API vrací 504 a vrátí kvótu za položky, které nedokončilo, takže jste účtováni jen za dokončenou práci. Pokud vidíte timeouty, posílejte menší dávky.
- 400 — empty_batch, batch_too_large, missing_text nebo text_too_long.
- 404 — skupina v kontextu položky není taková, kterou spravujete.
- 403 plan_required — dávkový koncový bod vyžaduje Pro nebo vyšší.
- 504 timeout — dávka běžela příliš dlouho; nedokončené položky jsou vráceny. Posílejte méně textů.