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

Что это

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

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

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

Зачем это владельцу сети групп

• Join-desk в вебе — очередь заявок с risk score, bulk approve/decline, ЛС-алерты с кнопками — не нужно жить в чате.
• Быстрый старт — пресеты (ЖК / маркет / тихий / агрессивный), копирование политики на другие чаты, wizard в Telegram после первого включения бота.
• Контроль из ЛС — /group N: pending, статус, вкл/выкл капчи без панели.
• Сеть без чужих чёрных списков — opt-in shared bans между вашими группами; CAS/Lols — как внешние банлисты рядом.
• Честный freemium — 1 группа любого размера бесплатно + все группы до 5 000 человек (см. Тариф).

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

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

Free: 1 группа любого размера + все группы ≤5 000 участников. Со 2-й крупной (>5 000) — заявка на тариф. Если квота исчерпана, группа может остаться unclaimed — заберите её /claim после расширения (см. Тариф).

Роли

Админка

Вступления

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

• Запрос на добавление (join_request_required — по умолчанию включён: вход через заявку, пока не сработают ручное одобрение / капча / квиз / пороги риска.
• Ручное одобрение — заявки висят во вкладке «Заявки», пока вы не решите (approve / decline / ban, в т.ч. массово).
• CAS на заявке — известный спамер сразу режется.
• Lols (lols_enabled — сверка с публичной базой api.lols.bot рядом с CAS: banned на входе → decline + ban.
• Автоотклонение / автоодобрение по порогам риска в настройках (0 = выкл).
• Квиз — один или несколько вопросов подряд (блоки через --- в настройках). Ответы в ЛС боту; при «муте до проверки» — после входа. Неверный ответ / таймаут режут всю цепочку.
• Уведомления о заявках notify_admins_on_join — ЛС с кнопками при ручном одобрении; notify_join_risk_min (0 = все) отсекает низкий риск.
• Капча — проверка в группе в муте: после правильного ответа мут снимается. Типы (включаются независимо; при нескольких — случайный выбор): эмодзи, математика (+ − × ÷), цифры. join_captcha_hard — без эмодзи (только math/digits; если типы не выбраны — math). Лимит попыток настраивается; неверный ответ / таймаут → кик или бан (флаги). Опционально join_captcha_min_risk: 0 = всем (если капча включена), иначе капча только при risk ≥ порога («умная капча»).
• Сеть банов celebro (opt-in) — shared_bans_contribute / shared_bans_consume: при бане за спам группа может отдавать сигнал; на заявке блок, если ≥ shared_bans_threshold разных владельцев уже сигналили (по умолчанию 2). Не путать с CAS/Lols.
• Мут до проверки — для квиза: пустить сразу и проверить в группе (а не в ЛС). Для капчи кнопкой мут в группе включается автоматически.
• 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) — отдельный канал (не id этой группы): пока пользователь не подписан на указанный @channel / id, сообщение в группе удаляется (бот должен быть админом того канала; пусто = выкл).
4. Сообщения от каналов / пересылки из каналов (если флаги включены) — см. Каналы в чате.
5. Flood: сообщения, стикеры, форварды, эмодзи — по лимитам окна → действие flood (по умолчанию delete_mute).
6. Стоп-фразы (spam / мат / реклама / нарко-пример): contains / exact / whole word / regex / example. Тип «мат» при включённом «Мут за маты» идёт в эскалацию варнов → мут, а не в обычный action фразы.
7. Мут за маты (profanity_mute_enabled — встроенный словарь + стоп-фразы «мат»: N предупреждений (сообщение удаляется), затем мут 1 ч; повтор после мута → мут 24 ч. Банов нет.
8. Шаблоны scam (типовые мошеннические формулировки: отзывы / «курьер»).
9. RU scam families (ЛС-рекрутинг, инвестиции, казино, adult, fake support, giveaway).
10. Нарко-реклама: правила (drug_ad_enabled) и опционально LLM (drug_ad_llm_enabled (fail-open без ключа / при timeout).
11. Soft-реклама по тематикам (вакансии, услуги, продажа, …) — режется или пропускается по дням / режимам / «любая кроме нелегальной». Короткие объявления услуг у «ограниченных» участников — как flood-action, иначе чаще только лог. Резюме / «ищу работу» без явной вакансии обычно не режутся как ads.
12. Дубликаты сообщений (порог / окно).
13. Mass-mention у новичков / на probation (порог упоминаний).
14. Защита от ссылок у новичков / на probation.
15. Защита от медиа без подписи у новичков: по умолчанию пометка + алерт админу; удаление — только у рискованного профиля (нет username/аватара и т.п.).
16. Message risk score — soft (лог) / hard (flood-action) по профилю, ссылкам, money/DM CTA, caps, emoji и т.д.

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

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

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

Разрешённая реклама (soft ads)

По умолчанию soft-объявления (вакансии, услуги, продажа и т.п.) режутся или помечаются как подозрение. Если в чате нужны «дни рекламы» — включите блок во вкладке «Настройки» → Антиспам.

• Реклама разрешена ads_allowed_enabled — мастер-флаг. Без него дни недели и «любая реклама» не пропускают soft-ads.
• Дни недели ads_allowed_weekdays — в какие дни действует режим «в дни рекламы». Пустой список = ничего не пропускать.
• Любая реклама кроме нелегальной ads_allow_any — в отмеченные дни пропускает soft-объявления любой тематики (режимы тематик скрываются / не нужны). Скам, нарко, CAS, стоп-фразы — по-прежнему режутся.
• Режимы тематик (если «любая» выкл): для каждой темы — Выкл (резать), В дни рекламы (только выбранные weekdays), Всегда (при включённом мастер-флаге, любой день). Пустые режимы = все темы «в дни», как раньше.
• Тематики: вакансии, недвижимость, авто, животные, обучение, услуги, продажа, локальный бизнес.

Soft-ads ≠ легализация скама: «пиши в ЛС, заработок», нарко-шаблоны, CAS/Lols и ваши стоп-фразы работают независимо от дней рекламы.

Доверенные

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

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

Команды бота

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

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

• Пресеты — ЖК / сообщество, Маркет, Тихий, Агрессивный: одним кликом выставляют связку заявок / капчи / рекламы / anti-raid. Дальше можно править флаги вручную.
• Копирование настроек — применить политику этой группы к другим чатам владельца (без переноса стоп-фраз/модераторов).
• Статус бота — вкл/выкл автомодерацию. Пока выключен — правила не применяются.
• Приветствие — шаблон ({mention}, {name}, {username}, {groupName}, {botName}), автоудаление через N секунд.
• Заявки — запрос на добавление, ручное одобрение, квиз, капча (эмодзи / math / digits, join_captcha_hard, порог join_captcha_min_risk), мут до проверки, anti-raid, пороги риска, бан при ошибке / таймауте / автоотклонении. См. раздел «Вступления».
• Сеть банов — делиться сигналами / блокировать по сети / порог владельцев (shared_bans_*.
• Предупреждения и мут — лимит варнов, TTL, эскалация, длительности mute/warn-mute, мут за маты (словарь + эскалация warn → mute 1ч → mute 24ч), бан во всех группах (cross-chat), «удалять всех кого я забанил».
• Антиспам — CAS, Lols, обязательная подписка на канал (require_channel), blacklist ботов, link/media guard, scam / service-offer / RU families / message risk, нарко-реклама (правила + опционально LLM), разрешённая soft-реклама (дни / тематики / «любая кроме нелегальной»), дубликаты, каналы, кик ботов, арабские/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: 1 группа любого размера — бесплатно навсегда; дополнительные группы до 5 000 человек — тоже бесплатно. Со 2-й крупной группы (>5 000) — тариф ниже (заявка → ручное согласование). Фичи бота одинаковые на всех тарифах.

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

Рядом с другими ботами

• vs Lols: у нас веб-панель заявок, пресеты и политика soft-рекламы; Lols сильнее как «поставил и забыл» NN. Можно держать оба: мы читаем Lols API.
• vs Rose: Rose — команды и locks в чате; celebro — очередь заявок, риск-скоринг и сеть групп владельца в вебе.
• рядом с Combot: Combot — аналитика комьюнити и CAS-сеть; мы — операционный слой join-desk + антиспам. CAS используем как банлист.
• vs Shieldy: Shieldy — только капча на входе; у нас полный пайплайн после входа + заявки + дайджесты.

Быстрый старт: пресеты в настройках группы, wizard после первого /enable в Telegram, /group N — статус и капча без веба. Opt-in сеть банов celebro — в настройках «Делиться / Блокировать по сети».

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 на другой канал (не путать с id этой группы): писать здесь можно только после подписки на указанный @channel / id; пусто = выкл (см. антиспам-пайплайн).

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