Пакетний ендпоінт проганяє до 20 текстів через антиспам-рушій Telm одним POST, повертаючи вердикт для кожного. Він працює лише на правилах (без AI-рівня) і доступний на тарифі Pro та вище. Квота списується за елемент, тож пакет із десяти текстів витрачає десять викликів. Для одного тексту з необов'язковою AI-перевіркою використовуйте звичайний ендпоінт перевірки спаму.
1Що робить пакетна перевірка спаму
Пакетна перевірка спаму дозволяє оцінити багато текстів одразу, замість робити один запит на повідомлення. Ви надсилаєте POST на /spam/check-batch з масивом елементів і отримуєте масив вердиктів у тому самому порядку — ідеально для класифікації бэклогу повідомлень, модерації стрічки коментарів чи оцінки якості визначення на вибірці.
Пакет проганяє той самий рушій правил, що захищає живі групи, але не запускає AI-рівень, що тримає кожен запит швидким і передбачуваним. Якщо вам потрібна AI-перевірка, використовуйте одиночний ендпоінт перевірки спаму з увімкненою опцією AI, по одному тексту за раз.
- Ендпоінт: POST /api/public/v1/spam/check-batch.
- Оцінює до 20 текстів за запит, вердикти повертаються в порядку введення.
- Лише правила: AI-рівень у пакетному режимі не запускається.
2Формат запиту
Тіло запиту — це JSON-об'єкт з масивом items. Кожен елемент має обов'язкове поле text та необов'язковий об'єкт context, що дзеркалить те, що бачить живий рушій — group_id, відправника user_telegram_id, чи є відправник новим користувачем, username та прапорці на кшталт allow_sales і crypto_community.
Коли елемент містить group_id у своєму context, перевірка застосовує власні правила й налаштування цієї групи, тож ваш акаунт має бути адміном цієї групи, інакше весь запит відхиляється. Пропустіть контекст групи, щоб оцінити проти глобального набору правил.
- Поле верхнього рівня: items — масив від одного до двадцяти записів.
- Кожен елемент: text (обов'язкове) та необов'язковий об'єкт context.
- Context може нести group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- Контекст групи вимагає, щоб ви адміністрували цю групу.
3Формат відповіді
Відповідь — це JSON-об'єкт з масивом results — один вердикт на вхідний елемент, у тому самому порядку — та об'єктом quota, що показує ваш лічильник використання, денний ліміт і час скидання.
Кожен вердикт каже вам класифікацію та чому. Поле verdict — це одне зі spam, suspicious чи clean. Поруч із ним ви отримуєте числовий score та confidence, recommended_action (одне з none, review, warn, mute, kick, ban чи delete), список categories, зрозумілі людині reasons, назви matched_rules та мапу signals з окремими внесками в оцінювання.
- results — один вердикт на елемент, у порядку введення.
- verdict — spam, suspicious чи clean.
- Кожен вердикт також має score, confidence, recommended_action, categories, reasons, matched_rules та signals.
- quota — used, limit та reset_at, продубльовані в тілі.
4Ліміти та вартість квоти
Пакет обмежено 20 елементами на запит, а кожен текст обмежено 10 000 символів. Усе тіло запиту також має стелю розміру, тож дуже великі пейлоади відхиляються до обробки. Якщо у вас більше 20 текстів, розбийте їх на кілька запитів.
Квота списується за елемент, а не за запит: пакет із десяти текстів витрачає десять викликів з вашої денної квоти. Це той самий бюджет, описаний у лімітах і квотах API, і відповідь несе звичні заголовки X-Quota-Limit, X-Quota-Used та X-Quota-Reset.
- До 20 елементів на запит; до 10 000 символів на текст.
- Вартість квоти дорівнює кількості елементів у пакеті.
- Застосовуються стандартні заголовки X-Quota-*, плюс об'єкт quota в тілі.
5Помилки та тайм-аути
Погані запити повертають 400 з конкретним кодом: порожній масив items, пакет понад ліміт елементів, відсутній text чи text понад ліміт довжини. Контекст групи, яку ви не адмініструєте, повертає 404 для цього елемента. Тариф нижче Pro повертає 403 з кодом plan_required.
Якщо обробка пакета перевищує свій часовий бюджет, API повертає 504 і повертає квоту за елементи, які не встиг завершити, тож ви платите лише за завершену роботу. Якщо ви бачите тайм-аути, надсилайте менші пакети.
- 400 — empty_batch, batch_too_large, missing_text чи text_too_long.
- 404 — група в контексті елемента не є тією, яку ви адмініструєте.
- 403 plan_required — пакетний ендпоінт потребує Pro чи вище.
- 504 timeout — пакет виконувався надто довго; за незавершені елементи квота повертається. Надсилайте менше текстів.