Документация celebro_antispam_bot

Что это

celebro_antispam_bot — связка бота в Telegram и панели на сайте. Бот в Telegram: @celebro_antispam_bot; панель и эта документация — тот же продукт.

Бот сидит в группе как администратор и автоматически режет спам, проверяет заявки, шлёт приветствия и выполняет модераторские команды. Панель нужна для разбора очереди заявок, просмотра сообщений, участников, санкций, логов и тонкой настройки правил.

• Вход: email/пароль или Telegram Login Widget.
• После логина открывается раздел «Группы».
• Все действия бота пишутся в логи модерации группы.
• Интерфейс панели: русский / English / Español, светлая / тёмная / системная тема.
• Банлисты CAS и Lols, защита от каналов (banChatSenderChat), обязательная подписка на канал, «умная» капча по риску, чистка join-notices после approve по заявке, команды /check, /info, /report.

Быстрый старт

1. Зарегистрируйтесь на сайте или войдите через Telegram. Новые пользователи получают роль владельца (owner).
2. В разделе Аккаунт привяжите Telegram (кнопка ссылки открывает бота с кодом /start link_…). Без привязки бот не сможет связать вас с группами и ЛС-уведомлениями.
3. Добавьте бота в группу администратором (нужны права на удаление сообщений и бан участников). Удобно из ЛС бота: команда /add — Telegram предложит выбрать чат и добавит бота.
4. Группа появится в админке в «Группы». По умолчанию бот выключен (bot_enabled = false: автомодерация не работает, пока вы не включите его переключателем в шапке группы / во вкладке «Настройки» → «Статус бота», либо командой /enable.
5. Откройте вкладку Настройки, подстройте защиты и включите бота.

По умолчанию у владельца ограниченная квота бесплатных групп (обычно 1). Дополнительные — через раздел «Тариф». Если квота исчерпана, группа может сохраниться как unclaimed — заберите её командой /claim после расширения тарифа (см. Тариф).

Роли

Админка

Вступления

Когда человек подаёт заявку в группу (или входит, если включён режим «мут до проверки»), бот считает risk score по сигналам: нет username, цифры в нике, арабский/CJK скрипт, «промо» в имени, нет аватара и др.

• Запрос на добавление (join_request_required — по умолчанию включён: вход через заявку, пока не сработают ручное одобрение / капча / квиз / пороги риска.
• Ручное одобрение — заявки висят во вкладке «Заявки», пока вы не решите (approve / decline / ban, в т.ч. массово).
• CAS на заявке — известный спамер сразу режется.
• Lols (lols_enabled — сверка с публичной базой api.lols.bot рядом с CAS: banned на входе → decline + ban.
• Автоотклонение / автоодобрение по порогам риска в настройках (0 = выкл).
• Квиз — один или несколько вопросов подряд (блоки через --- в настройках). Ответы в ЛС боту; при «муте до проверки» — после входа. Неверный ответ / таймаут режут всю цепочку.
• Капча — кнопка «я не бот» в группе: человека пускают в муте, после нажатия мут снимается. Опционально join_captcha_min_risk: 0 = всем (если капча включена), иначе капча только при risk ≥ порога («умная капча»).
• Мут до проверки — для квиза: пустить сразу и проверить в группе (а не в ЛС). Для капчи кнопкой мут в группе включается автоматически.
• Anti-raid — защита от волны join-заявок (см. ниже).
• Чёрный список владельца — флаги «общий blacklist ботов» и «удалять всех кого я забанил» режут повторный вход по истории банов / отклонённых.
• Чистка join-notice по заявке — после approve Telegram часто не шлёт new_chat_members («X принят в группу»). При delete_join_service_messages бот помечает pending notice, удаляет message_id − 1 рядом с welcome/капчей, а если webhook не пришёл — шлёт короткое probe-сообщение и сносит notice отложенной джобой.
• Просроченные challenge автоматически истекают (scheduler каждую минуту).
• Во вкладке «Заявки» можно синхронизировать висящие pending-заявки из Telegram, если очередь в панели разошлась с реальностью.

Дополнительно: кик чужих ботов при входе, раздельный блок арабских и китайских (CJK) ников, бан при ошибке / таймауте квиза или при автоотклонении (настраивается), уведомления админам в Telegram о новых / high-risk заявках.

Anti-raid

Если за короткое окно на группу сыпется слишком много заявок на вступление, включается временный lock: новые заявки бот отклоняет автоматически, чтобы не захлебнуться рейдом.

• По умолчанию выключено. Включается во вкладке «Настройки» → блок заявок на вступление.
• Параметры: сколько заявок за окно (по умолчанию 15 / 60 сек), сколько минут держать lock (по умолчанию 15), действие — decline или decline + ban.
• При срабатывании админам в Telegram уходит одно уведомление. Пока lock жив, все новые заявки режутся с типом anti_raid.
• Уже висящие Pending не чистятся автоматически — их нужно разобрать вручную во вкладке «Заявки».

Anti-raid срабатывает до CAS / Lols / квиза / порогов риска: во время lock пайплайн проверки не гоняется по каждой заявке из волны.

Антиспам

На каждое сообщение в группе (кроме доверенных и админов чата) проходит пайплайн по порядку. Многие детекторы учитывают probation: новичок (окно link-guard в часах) или первые N сообщений участника.

1. CAS — глобальный чёрный список Combot → delete_ban.
2. Lols — база api.lols.bot → delete_ban (флаг lols_enabled, по умолчанию вкл).
3. Обязательная подписка на канал (require_channel) — пока пользователь не состоит в указанном @channel / id, сообщение удаляется (бот должен быть админом канала).
4. Сообщения от каналов / пересылки из каналов (если флаги включены) — см. Каналы в чате.
5. Flood: сообщения, стикеры, форварды, эмодзи — по лимитам окна → действие flood (по умолчанию delete_mute).
6. Стоп-фразы (ваши правила: contains / exact / whole word / regex / example).
7. Шаблоны scam (типовые мошеннические формулировки).
8. RU scam families (семейства русскоязычных scam-паттернов).
9. Короткие объявления услуг — у «ограниченных» участников как flood-action, иначе только лог.
10. Дубликаты сообщений (порог / окно).
11. Mass-mention у новичков / на probation (порог упоминаний).
12. Защита от ссылок у новичков / на probation.
13. Медиа без подписи у новичков / на probation.
14. Message risk score — soft (лог) / hard (flood-action) по профилю, ссылкам, money/DM CTA, caps, emoji и т.д.

Возможные действия правила:

• log_only — только лог
• warn — предупреждение (с эскалацией по лимиту)
• delete — удалить сообщение
• delete_mute — удалить + мут (по умолчанию 60 мин)
• delete_ban — удалить + бан

Админам в ЛС может прийти уведомление о срабатывании с кнопками review: false-positive → в доверенные, либо добавить в чёрный список группы.

Доверенные

Allowlist во вкладке «Доверенные»: scope — эта группа или все группы владельца. Участника можно найти по имени, @username или Telegram ID.

• Сообщения не проверяются антиспамом (CAS, Lols, флуд, стоп-фразы, скам-шаблоны, ссылки и т.п.) — бот их не удаляет и не глушит.
• При вступлении их не банит автокик ботов / отклонённых / «забаненных владельцем».
• Админы и создатель группы считаются доверенными автоматически — отдельно добавлять не нужно.
• Капча и ручные санкции из панели / команд модерации на них всё ещё действуют.

Команды бота

Настройки группы

Во вкладке «Настройки» у каждого флага есть справка «?». Блоки:

• Статус бота — вкл/выкл автомодерацию. Пока выключен — правила не применяются.
• Приветствие — шаблон ({mention}, {name}, {username}, {groupName}, {botName}), автоудаление через N секунд.
• Заявки — запрос на добавление, ручное одобрение, квиз, капча (в т.ч. порог join_captcha_min_risk), мут до проверки, anti-raid, пороги риска, бан при ошибке / таймауте / автоотклонении. См. раздел «Вступления».
• Предупреждения и мут — лимит варнов, TTL, эскалация, длительности mute/warn-mute, бан во всех группах (cross-chat), «удалять всех кого я забанил».
• Антиспам — CAS, Lols, обязательная подписка на канал (require_channel), blacklist ботов, link/media guard, scam / service-offer / RU families / message risk, дубликаты, каналы, кик ботов, арабские/CJK ники, floods, first-N, mass-mention.
• Системные сообщения — удаление join / leave / прочих service-сообщений Telegram с задержкой. Join-by-request notices («принят в группу») чистятся даже если Telegram не прислал new_chat_members.
• Уведомления — о заявках и high-risk (порог риска для нотификации).
• Slow mode / ночной режим — ограничение права писать ночью по часам; slow mode в секундах.

Тариф

Free: любая группа до 500 человек — бесплатно. Группы свыше 500 участников — по тарифу ниже (заявка → ручное согласование). Фичи бота одинаковые на всех тарифах.

• В разделе Тариф смотрите квоту групп, лимит участников и создавайте заявку. В комментарии укажите ссылки на чаты и нужный тир.
• Заявка обрабатывается вручную; после оплаты поднимаем квоту и/или лимит участников.
• Если группа уже добавлена, но квоты или размера не хватило, она может остаться unclaimed. После расширения тарифа выполните в группе /claim.
• Если бесплатная группа выросла сверх лимита — бот продолжает работать, но в панели и в ЛС появится напоминание оставить заявку на апгрейд.

CAS и Lols

celebro_antispam_bot сверяет пользователей с двумя публичными банлистами (на заявках и в пайплайне сообщений):

• CAS (cas_enabled — Combot Anti-Spam по Telegram user id.
• Lols lols_enabled — api.lols.bot (GET /account?id= → banned. По умолчанию включено (как CAS).

При срабатывании: на заявке — decline + ban; в чате — delete + ban (delete_ban. Ответы кэшируются (TTL из config/antispam.php).

При коммерческом использовании CAS указывайте «Powered by CAS» (как в футере админки).

Каналы в чате

В Telegram участник может писать от имени канала (sender_chat — типичный спам-паттерн.

• Блокировать сообщения от каналов block_channel_messages — удаляет сообщение и банит канал в группе через banChatSenderChat (канал больше не сможет писать от своего имени, пока его не разбанят).
• Посты привязанного discussion-канала и автофорварды is_automatic_forward не трогаются.
• Блокировать пересылки из каналов block_channel_forwards — ручные форварды из каналов; автопосты linked channel снова пропускаются.
• Обязательная подписка require_channel — отдельный gate: писать в группу можно только после подписки на указанный канал (см. антиспам-пайплайн).

Боту нужны права админа с удалением сообщений и restrict/ban. Для require_channel бот также должен видеть участников целевого канала (обычно admin там).