Wsadowy punkt końcowy przepuszcza do 20 tekstów przez silnik antyspamowy Telm w jednym POST, zwracając werdykt dla każdego. Działa tylko na regułach (bez poziomu AI) i jest dostępny w planie Pro i wyższym. Przydział naliczany jest per element, więc wsad dziesięciu tekstów zużywa dziesięć wywołań. Dla pojedynczego tekstu z opcjonalnym sprawdzeniem AI użyj zwykłego punktu końcowego sprawdzania spamu.
1Co robi wsadowe sprawdzanie spamu
Wsadowe sprawdzanie spamu pozwala ocenić wiele tekstów naraz, zamiast wykonywać jedno żądanie na wiadomość. Wysyłasz POST na /spam/check-batch z tablicą elementów i otrzymujesz z powrotem tablicę werdyktów w tej samej kolejności — idealne do klasyfikacji zaległości wiadomości, moderacji strumienia komentarzy lub oceny jakości wykrywania na próbce.
Wsad uruchamia ten sam silnik reguł, który chroni żywe grupy, ale nie uruchamia poziomu AI, co utrzymuje każde żądanie szybkim i przewidywalnym. Jeśli potrzebujesz sprawdzenia AI, użyj pojedynczego punktu końcowego sprawdzania spamu z włączoną opcją AI, po jednym tekście naraz.
- Punkt końcowy: POST /api/public/v1/spam/check-batch.
- Ocenia do 20 tekstów na żądanie, werdykty zwracane w kolejności wejścia.
- Tylko reguły: poziom AI nie jest uruchamiany w trybie wsadowym.
2Format żądania
Treść żądania to obiekt JSON z tablicą items. Każdy element ma wymagane pole text oraz opcjonalny obiekt context, który odzwierciedla to, co widzi żywy silnik — group_id, nadawcę user_telegram_id, czy nadawca jest nowym użytkownikiem, username oraz flagi takie jak allow_sales i crypto_community.
Gdy element zawiera group_id w swoim context, sprawdzenie stosuje własne reguły i ustawienia tej grupy, więc Twoje konto musi być administratorem tej grupy, bo inaczej całe żądanie jest odrzucane. Pomiń kontekst grupy, aby oceniać wobec globalnego zestawu reguł.
- Pole najwyższego poziomu: items — tablica od jednego do dwudziestu wpisów.
- Każdy element: text (wymagane) oraz opcjonalny obiekt context.
- Context może nieść group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Kontekst grupy wymaga, abyś administrował tą grupą.
3Format odpowiedzi
Odpowiedź to obiekt JSON z tablicą results — jeden werdykt na element wejścia, w tej samej kolejności — oraz obiektem quota pokazującym Twój licznik zużycia, dzienny limit i czas resetu.
Każdy werdykt mówi Ci klasyfikację i dlaczego. Pole verdict to jedno ze spam, suspicious lub clean. Obok niego dostajesz liczbowy score i confidence, recommended_action (jedno z none, review, warn, mute, kick, ban lub delete), listę categories, czytelne dla człowieka reasons, nazwy dopasowanych matched_rules oraz mapę signals z poszczególnymi wkładami punktacji.
- results — jeden werdykt na element, w kolejności wejścia.
- verdict — spam, suspicious lub clean.
- Każdy werdykt ma też score, confidence, recommended_action, categories, reasons, matched_rules i signals.
- quota — used, limit i reset_at, odbite w treści.
4Limity i koszt przydziału
Wsad jest ograniczony do 20 elementów na żądanie, a każdy tekst do 10 000 znaków. Cała treść żądania ma również pułap rozmiaru, więc bardzo duże ładunki są odrzucane przed przetworzeniem. Jeśli masz więcej niż 20 tekstów, rozdziel je na kilka żądań.
Przydział naliczany jest per element, nie per żądanie: wsad dziesięciu tekstów zużywa dziesięć wywołań z Twojego dziennego przydziału. To ten sam budżet opisany w limitach i przydziałach API, a odpowiedź niesie zwykłe nagłówki X-Quota-Limit, X-Quota-Used i X-Quota-Reset.
- Do 20 elementów na żądanie; do 10 000 znaków na tekst.
- Koszt przydziału równa się liczbie elementów we wsadzie.
- Obowiązują standardowe nagłówki X-Quota-*, plus obiekt quota w treści.
5Błędy i przekroczenia czasu
Złe żądania zwracają 400 z konkretnym kodem: pusta tablica items, wsad ponad limit elementów, brakujący text lub tekst ponad limit długości. Kontekst grupy, której nie administrujesz, zwraca 404 dla tego elementu. Plan poniżej Pro zwraca 403 z kodem plan_required.
Jeśli przetwarzanie wsadu przekroczy swój budżet czasu, API zwraca 504 i zwraca przydział za elementy, których nie ukończyło, więc płacisz tylko za pracę, która się zakończyła. Jeśli widzisz przekroczenia czasu, wysyłaj mniejsze wsady.
- 400 — empty_batch, batch_too_large, missing_text lub text_too_long.
- 404 — grupa w kontekście elementu nie jest tą, którą administrujesz.
- 403 plan_required — wsadowy punkt końcowy wymaga Pro lub wyższego.
- 504 timeout — wsad działał zbyt długo; nieukończone elementy są zwracane. Wyślij mniej tekstów.