Пакетный эндпоинт прогоняет до 20 текстов через антиспам-движок Telm за один POST, возвращая вердикт для каждого. Он работает только на правилах (без уровня ИИ) и доступен на тарифе Pro и выше. Квота списывается за элемент, поэтому пакет из десяти текстов тратит десять вызовов. Для одного текста с опциональной проверкой ИИ используйте обычный эндпоинт проверки спама.
1Что делает пакетная проверка спама
Пакетная проверка спама позволяет оценивать много текстов сразу, вместо того чтобы делать по одному запросу на сообщение. Вы отправляете POST на /spam/check-batch с массивом элементов и получаете обратно массив вердиктов в том же порядке — идеально для классификации накопившихся сообщений, модерации ленты комментариев или оценки качества детекта на выборке.
Пакет запускает тот же движок правил, что защищает живые группы, но не запускает уровень ИИ, что держит каждый запрос быстрым и предсказуемым. Если вам нужна проверка ИИ, используйте одиночный эндпоинт проверки спама с включённой опцией ИИ, по одному тексту за раз.
- Эндпоинт: POST /api/public/v1/spam/check-batch.
- Оценивает до 20 текстов за запрос, вердикты возвращаются в порядке ввода.
- Только правила: уровень ИИ в пакетном режиме не запускается.
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 — пакет выполнялся слишком долго; незавершённые элементы возвращаются. Отправляйте меньше текстов.