TgDev

Я разрабатываю новый движок для tgdev ботов. В настоящий момент происходит постепенный процесс перевода TgDev ботов на новый движок. На новый движок переведены все боты-модераторы за исключением ботов @orgrobot и @wikirobot.

Далее следует список существующих TgDev ботов, уже перешедших на новый движок.

ВЫ МОЖЕТЕ ИСПОЛЬЗОВАТЬ ЛЮБОЙ ИЗ ЭТИХ БОТОВ, ОНИ ТЕПЕРЬ ВСЕ ОДИНАКОВЫЕ.

Ранее каждый бот из этого списка выполнял свою отдельную задачу. Теперь каждый из этих ботов обладает суммарным фунционалом всех ботов из списка. Если у вас в чате были установлены несколько ботов из списка, вам нужно оставить только один бот! Иначе боты будут писать одинаковые информационные сообщения т.к. один и тот же модуль будет выполнять свою задачу в каждом из этих ботов.

ВНИМАНИЕ! Боты, перешедшие на новый движок, не имеют веб-интерфейса для управления. Если ранее вы управляли этими ботами через сайт tgdev.io, то сейчас такой возможности временно нет.

ВНИМАНИЕ! Боты, перешедшие на новый движок, управляются новыми командами, описанными в текущем документе. Старые команды НЕ РАБОТАЮТ.

Содержимое документации

Установка бота в чат

Следуйте этим шагам:

  • Добавьте бота (см. список выше) в ваш чат.
  • Дайте боту разрешение на удаление сообщений, на бан пользователей и на закрепление сообщений. Никаких других разрешений не требуется.
  • Активируйте нужные модули. По-умолчанию, в новом чате большинство модулей неактивны. Вы можете активировать модуль с помощью настройки модуля active.

Основные принципы работы с ботом

  • Для настройки бота в конкретной группе вам нужно писать команды бота непосредственнов в эту группу, либо же выбрать активный чат в личной переписке с ботом и слать команды боту в личку. Подробнее смотрите раздел способы управления ботом.
  • Ботом может управлять любой администратор чата
  • Бот не удаляет сообщения администраторов. Если вы хотите протестировать, как бот удаляет сообщения, вам нужно писать сообщения от обычного пользователя, не являющегося администратором чата.

Бот автоматически определяет новых администраторов. Вы можете проверить, считает ли вас бот администратором, с помощью команды /tgdev check. Если по какой-то причине бот не распознаёт пользователя как администратора, используйте команду /tgdev reload_admins, чтобы принудительно обновить список всех администраторов. Эту команду нельзя использовать в личных сообщениях с ботом, вам нужно ввести эту команду в тот чат, список администраторов которого, вы хотите обновить.

Основные причины, почему бот может не работать

Если бот "не работает" (что бы это ни значило) в вашем чате, используйте следующую последовательность действий, чтобы проанализировать ситуацию:

  • Во-первых, не нужно тестировать удаление сообщений через аккаунт администратора чата. Даже правильно настроенный модель не будет удалять сообщения, написанные администратором. Вам нужно тестировать удаление сообщений аккаунтом, не имеющим прав администратора.
  • Далее проверьте, что вы не забирали у бота право писать в чат, если вы это сделали, то бот ничего вам не сможет сказать, даже если захочет
  • Далее проверьте командой /tgdev check, что у вас есть право управления ботом. Возможно, вам нужно будет перезагрузить список администраторов. Подробности читайте в разделе "Основные принципы работы с ботом". Внимание, бот молча удаляет команды управления, отправленные в группу пользователем, которого бот не считает администратором.
  • Далее проверьте, что в выводе команды /tgdev check написано, что у бота есть нужные права администратора. Например, если у бота нет права на удаление сообщение, то удалять сообщения у бота не получится.
  • Далее проверьте, что у нужного вам модуля включена настройка "active". Даже правильно настроенный модуль не будет ничего делать, если он отлючен через эту настройку. По-умолчанию, все модули отключены! Кроме того, например, модуль grep автоматически сам не включится, после того как вы добавите слова в список запрещённых слова. Вам нужно будет явно включить модуль.
  • Некоторые модули не будут ничего делать, даже если вы их активировали. Такие модули вам нужно предварительно настроить: добавить запрещённые слова, включить нужные фильтры модуля и так далее. Например, модуль grep удаляет сообщения с запрещёнными словами. По-умолчанию, список запрещённых слов пустой, поэтому после активации модуль grep не будет ничего удалять.

Способы управления ботом

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

Второй способ: вводить команды в личку боту. Команды нужно вводить самые обычные. Но предварительно нужно выбрать группу, к которой эти команды будут применяться. При вводе команд управления ботом в личку боту, результат каждой команды будет содержать название выбранной группы. Таким образом вы вседа будете понимать, какая группа сейчас является активной.

Команды выбора группы в личке:

  • /tgdev select ID - выбрать группу, к которой будут применяться команды, введённые в личку боту. Тут ID - это числовой идентификатор группы. Чтобы узнать идентификатор чата вы можете ввести в чат команду /tgdev check в ответе на которую будет указан в том числе и идентификатор чата. Обратите внимание, идентификатор чата начинается с последовательности "-100" т.е. является отрицательным числом.
  • /tgdev select - если написать команду select без параметров, то она отобразит кнопку для выбора чатов. При нажатии на кнопку отроется список чатов, в котором можно выбрать нужный чат.
  • /tgdev deselect - сбросить активную группу. После вызова этой команды, попытки введения команд настройки бота в личку бота будут приводить к показу сообщения, что активная группа не выбрана.

Управление модулями бота

Функции бота разбиты на части, называемые модулями. Модуль решает одну задачу или несколько задач схожей тематики. Модуль имеет настройки. В каждом чате нужно заново задавать настройки модуля. По-умолчанию, любой модуль неактивен. Каждый модуль обладает стандартными настройками, а также настройками, специфичными для задачи, решаемой модулем. Список настроек модуля вы можете узнать в конкретном разделе документации, посвящённом нужному модулю.

Любые настройки любых модулей делятся на две главных группы:

  1. Скалярные настройки т.е. настройки, содержащие одиночное значение. Настройки, содержащие одиночные значения, бывают следующих типов: логическая, числовая, текстовая. Эти настройки изменяются командой set. Подробное описание работы со скалярными настройками смотрите в разделе Управление скалярными настройками.
  2. Настройки содержащие список значений. Эти настройки изменяются командами add и remove. Смотрите описание работы с этими командами в разделе Управление настройками-списками

Команда отображения всех настроек модуля:

  • /tgdev/MODULE config - отобразить конфигурацию модуля. Вместо MODULE нужно использовать имя конкретного модуля. В случае если вы добавили слишком много элементов в конфигурацию модуля, команда отображения конфигурации модуля ничего не покажет т.к. размер сообщения превысит ограничение системы Телеграм на максимальный размер сообщения. В таком случае, едиственный способ увидеть конфигурацию модуля -- воспользоваться командой экспорта конфига в файл, смотрите раздел сохранения конфигурации в файл.

Стандартные настройки, которые есть в каждом модуле

Каждый модуль имеет стандартные настройки, изменяющие поведение этого модуля:

  • active (логическая; по-умолчанию: выключена) -- активирует (включает) работу модуля в чате.
  • notification (логическая; по-умолчанию: включена) -- включает посылку ботом уведомлений в чат об удалённых сообщениях и других действиях бота.

Команды изменения скалярных настроек

Скалярные настройки -- это настройки, содержащие одиночное значение: число, строку или логическое значение.

Если настройка имеет логический тип, то в качестве значений нужно использовать "yes" и "no", чтобы, соотвественно, включить или отключить настройку. Для числовых и текстовых значений вам нужно указывать непосредственно сами число или текст.

Команда изменения скалярной настройки имеет следующую форму:

  • /tgdev/MODULE set NAME VALUE - задать значение скалярной настройки модуля. Вместо MODULE нужно использовать имя конкретного модуля, вместо NAME -- имя настройки, вместо VALUE -- значение настройки.

Команды изменения настроек-списков

Многие модули обладают настройками в виде списка. Чаще всего это списки для запрещённых слов или для запрещённых регулярных выражений. В документации по каждому модулю перечислены настройки-списки, которые вы можете настраивать.

Далее представлены команды для управления настройками-списками:

  • /tgdev/MODULE add LIST WORD -- добавить слово в список. Вместо MODULE нужно использовать имя конкретного модуля, вместо LIST -- имя списка, вместо WORD -- конкретное слово, которое вы хотите добавить в список.
  • /tgdev/MODULE remove LIST WORD -- удалить слово из списка. Вместо MODULE нужно использовать имя конкретного модуля, вместо LIST -- имя списка, вместо WORD -- конкретное слово, которое вы хотите удалить из списка.
  • /tgdev/MODULE dump LIST -- отобразить содержимое списка в виде многострочного текста. Каждый элемент списка будет отображён на отдельной строке. Вместо MODULE нужно использовать имя конкретного модуля, вместо LIST -- имя списка.
  • /tgdev/MODULE clear LIST -- очистить содержимое списка. После выполнения команды все элементы списка будут удалены. Вместо MODULE нужно использовать имя конкретного модуля, вместо LIST -- имя списка.

Для добавления в список нескольких значений за раз, вам нужно использовать ту же самую команду, как для добавления одного значения, но указать каждое следующее значение на отдельной строке. Пример такой команды следует далее. Обратите внимание, это одна команда, состоящая из нескольких строк. После каждого значения идёт перенос строки:

/tgdev/grep add word bitcoin
dogecoin
ethereum

Аналогичным образом можно удалять из списка множество значений с помощью команды remove.

Диагностические команды

  • /tgdev check - проверить правильность установки бота
  • /tgdev config - отобразить конфигурацию всех модулей. В случае если вы добавили слишком много элементов в конфигурацию бота, команда отображения конфигурации ничего не покажет т.к. размер сообщения превысит ограничение системы Телеграм на максимальный размер сообщения. В таком случае, едиственный способ увидеть конфигурацию -- воспользоваться командой экспорта конфига в файл, смотрите раздел сохранения конфигурации в файл.
  • /tgdev reload_admins - обновить список администраторов чата. Обычно эта команда не нужна т.к. в большинстве случаев бот автоматически определяет, что участник группы стал администратором, или что у участника группы забрали права администратора. Не используйте эту команду в личных сообщениях с ботом. Вводите эту команду в тот чат, список администраторов которого, вы хотите обновить.

Белый список каналов

Если канал (или чат) находятся в белом списке, все модули бота будут пропускать сообщения этого канала. Эта настройка нужна в двух случаях:

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

Естественно, настраивать белый список каналов имеет смысл только, если какие-то фильтры модуля препятствуют появлению сообщений из нужных каналов.

Для изменения белого списка каналов вам нужно работать с настройкой-списком channel_whitelist модуля system.

Белый список доменов

Некоторые модули бота могут удалять сообщения при обнаружении в них ссылок на веб-сайты. Вы можете добавлять доменные имена (домены) в белый список доменов для того, чтобы модули бота не удаляли сообщения со ссылками на эти домены. Можно разрешать целые доменные зоны, например используйте значение "ru" для разрешения ссылок на все домены в зоне "ru".

Модули бота, на которые влияет белый список доменов:

  • модуль sandbox в режиме обработки карантина safe_hours

Для изменения белого списка доменов вам нужно работать с настройкой-списком hostname_whitelist модуля system.

Белый список пользователей

Для того, чтобы модули бота не удаляли сообщения конкретного пользователя, вам нужно добавить числовой идентификатор пользователя в белый список пользователей.

Для изменения белого списка пользователей вам нужно работать с настройкой-списком user_whitelist модуля system -- белый список пользователей в модуле system влияет на работу всех модулей.

В некоторых модулях (например, mute) есть свой белый список пользователей, который влияет только на работу модуля, которому он принадлежит -- наличие таких списков уточняйте в документации нужного вам модуля.

Обратите внимание. В белый список пользователей вам нужно добавлять числовые идентификаторы телеграм аккаунтов. Это не username, это число. Узнать этот идентификатор вы можете, например, если ответите в чате, где установлен tgdev бот, на сообщение нужного пользователя командой +whois.

Задание настроек времени

Все настройки времени в боте задаются в формате "ЧЧ:ММ", где ЧЧ - это часы, а ММ - минуты. Нужно использовать двузначные числа, например, пять минут первого надо задавать в формате "00:05".

Все настройки времени бота в конкретном чате обрабатываются с учётом часовой зоны этого чата. По умолчанию используется часовая зона с нулевым смещением относительно нулевого мередиана. Если, например, основная аудитория группы находится Ленинграде т.е. в часовой зоне, имеющей смещение, равное трём часам, то нужно задать соответствующую часовую зону в настройках этого чата командой /tgdev/system set time_zone 03:00.

Настройка часовой зоны чата едина для всех модулей. Часовая зона хранится в модуле system.

Файлы конфигурации чата

Конфигурацию модулей любого чата можно сохранить в файл. Можно сохранять как настройки всех модулей, так и настройки явно выбранных модулей. Далее файл настроек можно использовать для восстановления настроек чата или для применения этих настроек к другому чату. Работать с файлами настроек можно только через личные сообщения с ботом.

Внимание. При импорте файла конфигурации настройки из файла ПЕРЕЗАПИШУТ существующие настройки чата.

Команды работы с файлом настроек:

  • /tgdev/config export - сохранить настройки всех модулей в файл.
  • /tgdev/config export MODULES - сохранить настройки выбранных модулей в файл. Здесь MODULES означает список имён модулей, указанных через запятую. Пример команды: /tgdev/config export mute,grep
  • /tgdev/config import - применить файл настроек к чату. Эту команду нужно вводит в ответе на сообщение, содержащее файл настроек. Файл настроек НЕ применяется к чату выбранному командой /tgdev select. Вам будет предложено явно выбрать чат, к которому должны быть применены настройки из файла. Настройки из файла ПЕРЕЗАПИШУТ существующие настройки чата.

При желании вы можете вручную отредактировать файл настроек в текстовом редакторе. А затем применить настройки из этого файла к нужному чату.

В файле настроек содержится информация о дате создания файла, а также о чате, из которого были экспортированы настройки. Эта информация не влияет на процесс импортирования настроек этого файла т.к. вы явным образом выбираете чат для применения настроек из файла.

Особенности работы с регулярными выражениями

В некоторых модулях можно использовать пользовательские регулярные выражения. Например, в модуле grep можно добавлять рег. выражения в список "regex". Для работы с регулярными выражениями используется rust библиотека regex. Ссылка на её документацию: docs.rs/regex/latest/regex/

Проверять, как работает регулярное выражение, удобно на сайте regex101.com. Не забудьте выбрать в меню слева "Rust" в списке движков для обработки регулярных выражений.

Важные вещи, которые нужно знать:

  • при обработке регулярных выражений регистр букв не имеет значения
  • символы ^ и $ совпадают с началом и концом строк в многострочном тексте
  • символ . совпадает в том числе с переносом строки
  • look-around запросы не поддерживаются т.е. (?=...), (?!...), (?<=...) и (?<!..)
  • back-reference запросы не поддерживаются т.е. \1, \2 и т.д.

Уведомления об удалённых сообщениях

Каждый активный модуль, по-умолчанию, отправляет в чат уведомление при удалении сообщения пользователя. В уведомлении написана причина, по которой было удалено сообщение. Уведомления любого модуля можно отключить с помощью настройки модуля "notification". Уведомления автоматически удаляются через пять минут.

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

Текст каждого уведомления содержит в конце символы "(???)", являющиеся ссылкой на информационную страницу сайта tgdev.io, содержащую подробности об удалённом сообщении. Такую информационную страницу удобно использовать для следующих задач:

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

Информационная страница об удалённом сообщении доступна в течении 24 часов с момента удаления сообщения.

Быстрые команды

Быстрые команды имеют простую короткую запись и позволяют админстратору чата быстро получить доступ к ряду фунций.

  • +mute - запрет пользователю писать сообщения в чат
  • +kick - исключение пользователя из чата с возможностью вернуться в чат
  • +ban - исключение пользователя из чата без возможности вернуться в чат (бан)
  • +unban - отмена запрета на вход пользователя в чат (отмена бана)
  • +del - удаление сообщения через заданное количество времени
  • +unpin - открепление (удаление из закреплённых) сообщения через заданное количество времени
  • +whois - вывести информацию об участнике чата

Некоторые быстрые команды требуют указать период времени. Период времени можно задать одним из двух способов:

  1. Значение inf означает бесссрочное период времени. Например, после выполнения команды +mute inf пользовать не сможет писать в чат, пока админ вручную не снимет с него ограничение.
  2. Значения вида m1, h1, d1, w1 соответствуют периодам времени в одну минуту, один час, один день и одну неделю, соответственно. Вместо единицы вы можете использовать другое число. Например, m33 означает период времени длиной в тридцать три минуты.

Команда +mute TIME запрещает пользователю писать сообщения в чат. Здесь TIME означает период времени, в течении которого будет действовать ограничение. Команду +mute нужно обязательно писать в ответе на сообщение, автора которого вы хотите ограничить.

У команды +mute есть расширенный вариант записи, в котором вы можете указать также причину ограничения. Например, в команде +mute d1 ругается матом весь текст команды, указанный после периода времени, будет являться значением причины. Причина ни на что не влияет и в данный момент используется лишь в информационном уведомлении, которое бот пишет в чат, если ему удалось ограиничить пользователя. Пример такого уведомления: Пользователю Алексей Алексеев запрещено писать сообщения до Dec 18, 2023 18:42 UTC, причина: ругается матом.

Команды +ban и +kick исключают пользователя из чата. Эти команды нужно вводить в ответе на сообщение пользователя, которого вы хотите исключить из чата. Отличие команды +kick от +ban в том, что первая команда разрешает пользователю вернуться в чат, тогда как вторая банит его навсегда. Обе команды поддерживают расширенный синтакси т.е. +ban REASON и +kick REASON, где REASON — это произвольный текст, который может содержать пробелы. Как и в случае +mute команды, причина не влият ни на что, а только лишь присутствует в уведомлении бота, в случае, если пользователь был успешно исключён из чата.

Команда +unban отменяет запрет на вход пользователя в чат или, другими словами, снимает бан. Эту команду нужно вводить в ответе на сообщение пользователя, которого вы хотите разбанить.

Команда +del TIME удаляет сообщение через заданное время. Здесь TIME задаётся в формате, описанном выше. Эту команду нужно вводить в ответе на сообщение, которое вы хотите удалить.

Команда +unpin TIME убирает сообщение из списка закреплённых сообщений через заданное время. Здесь TIME задаётся в формате, описанном выше. Эту команду нужно вводить в ответе на сообщение, которое вы хотите открепить.

Команда +whois выводит информацию об участнике чата. Эту команду нужно писать в ответ на сообщение пользователя, информацию о котором вы хотите увидеть. На данный момент времени (20 декабря 2023) команда выводит идентификатор, логин, а также, если таковая информация есть, статус участника чата и дата изменения статуса. Наиболее частый статус это просто обычный статус участника чата, а дата измения этого статуса означает дату входа участника в чат.

Модуль system

В системном модуле находятся настройки, влияющие на работу всех модулей.

Настройки модуля system:

  • time_zone (строковая) -- часовая зона чата. Значение настройки задаётся в виде "ЧЧ:ММ" или "-ЧЧ:ММ", если часовая зона имеет отрицательное смещение. Более подробно работа с временной зоной описана в разделе задание настроек времени
  • lang (строковая) -- задаёт язык сообщений бота. Значение настройки -- это двухбуквенный код языка. В данное время поддерживаются следующие языки: ru -- русский, en -- английский.

Настройки-списки модуля system:

  • user_whitelist(список чисел) -- список числовых идентификаторов пользователей, сообщения которых должны пропускать (не удалять) все модули. Подробнее об этом списке читайте в разделе белый список пользователей.
  • channel_whitelist (список чисел) -- список числовых идентификаторов каналов с которых разрешено пересылать сообщения в чат. Подробнее об этом списке читайте в разделе белый список каналов.
  • hostname_whitelist (список чисел) -- белый список доменов. Разрешает ссылки на страницы на доменах, содержащихся в этом списке. Подробнее об этом списке читайте в разделе белый список доменов.

Модуль grep

Модуль grep удаляет сообщения, содержащие слова из списка запрещённых слов. Список запрещённых слов вам нужно заполнить самостятельно.

Настройки-списки модуля grep:

  • word (список строк) -- этот список содержит запрещённые слова (или фразы), которые ищутся в тексте сообщения. Слова (или фразы) ищутся именно в том виде, как они записаны в списке. Регистр букв не учитывается. Засчитывается только полное совпадение запрещённого слова (или фразы) со словом (фразой) в тексте. Например, если запрещено слово "бесплатно", то будет удалено сообщение "скачать видео бесплатно", но не будет удалено сообщение "бесплатный сеанс магии". Вы можете использовать целые фразы: сообщение будет удалено, если текст сообщения будет содержать фразу и края фразы будут совпадать с краями слов в тексте. Например, если запрещена фраза "качать бесплатно", то будет удалено сообщение "Вы можете качать бесплатно воду", но не будет удалено сообщение "Вы можете скачать бесплатно воду".
  • regex (список строк) -- этот список содержит регулярные выражения. Максимальная длина регулярного выражения -- 255 символов. Если вы не знаете, что такое регулярные выражения, то скорее всего они вам не нужны. Для работы с регулярными выражениями на данный момент времени модуль grep использует rust библиотеку regex. Обязательно прочтите раздел документации Особенности работы с регулярными выражениями.

В каждом списке может содержаться не более 300 элементов.

Команды модуля grep:

  • /tgdev/grep analyze TEXT - найти все слова и регулярные выражения, которые совпадают с текстом. Здесь TEXT - это произвольный текст, который может в том числе содержать переводы строк.

Модуль langblock

Модуль langblock удаляет сообщения, написанные на запрещённом языке. Также есть возможность удалять сообщения, содержащие символ из запрещённого алфавита.

Для добавления языка в запрещённый список, вам нужно использовать код языка. Узнать код языка можно с помощью команды /tgdev/langblock analyze, указав её в ответе на анализируемое сообщение. Бот определит язык сообщения и покажет вам код языка. Также эта команда покажет вам наличие символов тех алфавитов, которые позволяет блокировать модуль langblock.

Поддерживаемые алфавиты:

  • arabic - символы арабского алфавита, буквы которого используются в арабском, иранском и других языках Востока.
  • cjk - иероглифы, использующиеся в китайском, японском, корейском и других языках юго-восточной Азии.

Настройки-списки модуля langblock:

  • lang (список строк) -- список запрещённых языков. Значения списка -- это коды языков. Узнать код языка можно с помощью команды /tgdev/langblock analyze, указав её в ответе на анализируемое сообщение.
  • script (список строк) -- список запрещённых алфавитов. Используйте значения из списка поддерживаемых алфавитов, доступного выше.

Модуль mute

Модуль mute удаляет любые сообщения, отправляемые пользователями в чат. Режим удаления сообщений можно включать как вручную, так и автоматически в заданный период времени.

Команды модуля mute:

  • /tgdev/mute enable all - включить режим удаления всех сообщений
  • /tgdev/mute disable all - выключить режим удаления всех сообщений
  • /tgdev/mute enable period - включить режим удаления сообщений в заданный период
  • /tgdev/mute disable period - выключить режим удаления сообщений в заданный период

Настройки модуля mute:

  • period_start (строковая) -- начало периода удаления сообщений
  • period_end (строковая) -- конец периода удаления сообщений

Для настроек period_start и period_end нужно использовать время в формате "ЧЧ:ММ", где ЧЧ - это часы, а ММ - минуты. Обязательно прочитайте раздел "Задание временных настроек", перед настройкой бота.

Настройки-списки модуля mute:

  • user_whitelist (список чисел) -- содержит числовые идентификаторы Telegram аккаунтов, сообщения которых модуль не должен удулять, даже если активен режим удаления сообщений. Обратите внимание, это отдельный белый список пользователей модуля mute! Есть также глобальный белый список пользователей, который находится в модуле system, действие которого распространяется на все модули, включая модуль mute.

Модуль nopig

Модуль nopig удаляет сообщения, содержащие ругательства. С помощью настройки "filter" можно включать и отключать различные фильтры ругательств.

Доступные фильтры ругательств:

  • ru-mat -- фильтр всех слов русского языка, образованных от матерных корней, а также от корня "хер". Также фильтр содержит некоторые грамматически неправильные написания матерных слов.
  • ru-bad -- фильтр ругательств русского языка, не являющихся матерными.
  • en-bad -- фильтр ругательств английского языка. На данный момент фильтр содержит всего лишь одно слово "fuck" :-)

Настройки-списки модуля nopig:

  • filter (список строк) -- список включенных фильтров ругательств

Модуль nohello

Модуль nohello удаляет сообщения, содержащие только приветствие и ничего более. Примеры подобных сообщений: "Привет!", "hi", "hello people", "добрый вечер".

Модуль nopm

Модуль nopm удаляет сообщения, в которых пользователь просит ответить ему в личные сообщения. Примеры подобных сообщений: "pm", "пиши в личку", "dm me!", "давай в лс". Модуль не удаляет сообщения, в которых кроме призыва писать в личные сообщения есть также другой текст, например: "Продаю слона. Пиши в ЛС.".

Модуль nohelp

Модуль nohelp удаляет сообщения, в которых пользователь просит о помощи. Удаляются только те сообщения, в которых больше нет никакой информации кроме самой просьбы о помощи. Примеры сообщений, которые будут удалены: "Help me!", "Помогите, пожалуйста", "прошу, помогите мне", "мне нужна помощь". Пример сообщения, которое не будет удалено: "Помогите мне, я ничего не понимаю".

Модуль sandbox

Модуль sandbox удаялет сообщения пользователя, находящегося в карантине. Каждый новый участник в чата попадает в карантин. Сроком карантина можно управлять. Срок задаётся в часах, прошедших с момента входа пользователя в чат. Если пользователь выходит и снова заходит в чат, то срок карантина начинает отсчитываться заново с нуля.

В модуле sandbox можно управлять тремя типами карантинов:

  • Карантин на публикацию ссылок и медиа-материалов. Регулируется настройками safe_hours и remove_media.
  • Карантин на публикацию любых сообщений. Регулируется настройкой mute_hours.
  • Карантин на публикацию просьбы написать ответ в личные сообщения. Регулируется настройкой nopm_hours.

Чтобы отключить карантин, задайте значение 0 (ноль) соответствующей настройке.

Настройки модуля sandbox:

  • safe_hours (число; ограничение: от 0 до 720; по-умолчанию: 24) -- количество часов действия карантина на публикацию ссылок.
  • remove_media (логическая, по-умолчанию: выключена) -- на время действия карантина на публикацию ссылок запрещает также публикацию фото, видео и других медиа-материалов. Полный список типов сообщений, считающихся медиа-материалами, представлен ниже.
  • mute_hours (число; ограничение: от 0 до 720; по-умолчанию: 0) -- количество часов действия карантина на публикацию любых сообщений
  • nopm_hours (число; ограничение: от 0 до 720, по-умолчанию: 0) -- количество часов действия карантина на публикацию просбы написать ответ в личные сообщения. В отличие от модуля nopm, модуль sandbox удаляет даже те сообщения, в которых кроме просьбы написать личное сообщение, есть другой текст. Пример сообщения, которое будет удалено: "Продам слона. Пиши в ЛС!".

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

Типы сообщений, считающихся медиа-материалами:

  • аудио-запись
  • игра
  • GIF-анимация
  • прикреплённый файл
  • фотография
  • видео-запись
  • голосовое сообщение
  • видео-заметка
  • контактная карточка
  • гео-позиция
  • стикер

Модуль uname

Модуль uname позволяет ограничивать действия пользователей, если в их имени или логине обнаружены запрещённые слова.

В разделе документации модуля uname используются следующие термины:

  1. имя пользователя -- это то имя, которое пользователи вводят в поля Имя и Фамилия при настройке своего профиля. Это то имя, которая отображается в сообщениях о действиях пользователя типа "Такой-то присоединился к чату". Это имя в заголовке профиля пользователя.
  2. логин пользователя -- это специальное имя, которое есть не у всех пользователей. Если оно есть, оно обычно пишется с символом "@" и является ссылкой на профиль пользователя. Логин пользователя может содержать только буквы английского алфавита, цифры и символ подчёркивания.
  3. алфавит -- совокупность всех символов, представленных алфавитом какого-либо языка. Фраза "в имени пользователя находится некий алфавит" означает, что некоторые символы имени пользователя принадлежат множеству символов этого алфавита.

Модуль uname обрабатывает следующие события:

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

  2. Пользователь уже находится в чате и написал сообщение. Если в его имени или логине найдены запрещённые слова, то сообщение пользователя будет удалено. Сам пользователь не будет выкинут из чата. Модуль не выкидывает уже существующих пользователей из чата, чтобы уберечь администратора от потери всех участников чата в случае направильной конфигурации списка запрещённых слов. Например, регулярное выражение .* совпадает с любым именем или логином.

Модуль uname содержит следующие настройки со списками:

  • name_word - запрещённые слова в имени пользователя.
  • name_regex - запрещённые регулярные выражения в имени пользователя.
  • login_word - запрещённые слова в логине пользователя.
  • login_regex - запрещённые регулярные выражения в логине пользователя.
  • name_script - запрещённые алфавиты в имени пользователя. Вы можете добавлять в этот список только алфавиты, поддерживаемые модулем uname -- смотрите их список далее.

Алфавиты, которые поддерживает модуль uname:

  • arabic - символы арабского алфавита, буквы которого используются в арабском, иранском и других языках Востока.
  • cjk - иероглифы, использующиеся в китайском, японском, корейском и других языках юго-восточной Азии.

Модуль freq

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

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

Важно. Количество сообщений, написанных пользователем, отсчитывается от начала текущего периода. Например, пользователь пишет сообщение в 14:13. Модуль freq рассчитывается количество его сообщений за час используя диапазон от 14:00 до 15:00. Это же верно и для суточного периода: количество сообщений пользователя отсчитывается от начала суток. Вы можете управлять настройкой временной зоны вашего чата, чтобы отсчёт выглядел более корректным. Смотрите раздел Задание настроек времени для справки, как изменить временную зону чата.

Настройки модуля freq:

  • limit_minute (число) -- максимальное количество сообщений, которые пользователю разрешено написать в чат в течение одной минуты.
  • limit_hour (число) -- максимальное количество сообщений, которые пользователю разрешено написать в чат в течение одного часа.
  • limit_day (число) -- максимальное количество сообщений, которые пользователю разрешено написать в чат в течение одного дня.
  • limit_flood (число) -- максимальное количество сообщений, которые пользователю разрешено написать подряд т.е. единым непрерывным потоком сообщений, который не прерывается сообщениями других пользователей.

Модуль nosticker

Модуль nosticker удаляет стикеры. В данный момент можно работать только со стикерпаками целиком т.е. нельзя запретить определённый стикер из стикерпака -- вы можете только запретить весь стикерпак.

Модуль nosticker может работать в одном из двух режимов:

  1. Разрешающий режим (включен по-умолчанию). В этом режиме модуль удаляет только те стикерпаки, которые вы явно запретили. Для запрещения стикерпака вам нужно добавить его идентификатор в список disabled_pack. Для активации этого режима нужно ВЫКЛЮЧИТЬ настройку default_delete.
  2. Запрещающий режим. В этом режиме модуль удаляет все стикерпаки, кроме тех, которые вы явно разрешили. Для разрешения стикерпака, вам нужно добавить его идентификатор в список allowed_pack. Для активации этого режима вам нужно ВКЛЮЧИТЬ настройку default_delete.

Настройки модуля nosticker:

  • default_delete (логическая, по-умолчанию: выключена) -- включение запрещающего режима

Настройки-списки модуля nosticker:

  • allowed_pack (список строк) -- список идентификаторов разрешённых стикерпаков. Этот список используется в запрещающем режиме.
  • disabled_pack (список строк) -- список идентификаторов запрещённых стикерпаков. Этот список используется в разрешающем режиме.

В разрешённых и запрещённых списках стикерпаков используются идентификаторы стикерпаков. Не путайте их с именами стикерпаков, которые вы видите при просмотрет стикерпака. Идентификатор стикерпака может состоять только из букв английского алфавита, цирф и знака подчёркивания. Чтобы узнать идентификатор стикерпака вам нужно ответить на сообщение, содержащее стикер, командой /tgdev/nosticker analyze.

Команды модуля nosticker:

  • /tgdev/nosticker analyze -- используйте эту команду в ответ на сообщение, содержащее стикер, чтобы узнать идентификатор стикерпака этого стикера.
  • /tgdev/nosticker disable_pack -- используйте эту команду в ответе на сообщение, содержащее стикер. Результатом выполнения команды будет запрет соответствующего стикерпака т.е. помещение его идентификатора в список disabled_pack. Также идентификатор этого стикерпака будет исключён из списка allowed_pack, если он там находился.

Модуль welcome

Модуль welcome пишет в чат приветствие, когда новый участник присоединяется к чату. Это приветствие в том числе видит каждый существующий участник чата.

Вы можете использовать стили в тексте приветствия. Размечать текст нужно с помощью HTML тэгов. Список поддерживаемых тэгов можно посмотреть в официальной документации Telegram: https://core.telegram.org/bots/api#html-style

В тексте приветствия можно использовать макросы. Макрос %user% заменится на имя пользователя. Другие макросы пока что не поддерживаются.

Настройки модуля welcome:

  • message (строка) -- текст приветственного сообщения.
  • message_timeout (число, по-умолчанию: 120) -- время в секундах, по прошествии которого приветственное сообщение будет скрыто.

Команды модуля welcome:

  • /tgdev/welcome show_message -- посмотреть, как выглядит приветственное сообщение

Модуль Watchdog

Модуль watchdog удаляет сообщения, удовлетворяющие заданным фильтрам. Также несколько фильтров ориентированы на работу с пользователями, а не сообщениями.

Настройки-списки модуля watchdog:

  • filter (список строк) -- список включенных фильтров. По-умолчанию, в новом чате все фильтры отключены! Для включения фильтра вам нужно добавить нужный фильтр в список filter. Для отключения фильтра вам нужно исключить нужный фильтр из списка filter.

Команды модуля watchdog:

  • /tgdev/watchdog analyze - команду нужно вводить в ответе на сообщение, подлежащее анализу. Команда выводит список всех возможных фильтров (независимо от того, какие фильтры включены в чате), которым удовлетворяет анализируемое сообщение.

Список фильтров, которые можно добавлять в настройку-список filter. Первое слово (цветное) в каждой строке -- это название фильтра. Для удобства фильтры сгруппированы по темам.

  • Ссылки:

    • link - сообщение, содержащее ссылку
    • mention - сообщение, содержащее @username
    • split_mention - сообщение, содержащее @ username в котором есть пробел после "@" символа
    • email - адрес электронной почты
    • text_mention - специальные упоминания пользователей, которые могу выглядеть как обычный текст https://telegram.org/blog/edit#new-mentions
  • Медиа:

    • sticker - стикер
    • gif - анимированное изображение в формате GIF
    • voice - запись голоса
    • attachment - прикрепленный файл
    • audio - аудиоклип
    • video - сообщение с видеофильмом
    • photo - фото файл
    • media_group - сообщение, которое содержит несколько медиа-объектов (обычно фотографии)
    • video_message - видеоклип
    • not_sticker - сообщение, которое НЕ ЯВЛЯЕТСЯ стикером
    • story - сообщение, содержащее историю
  • Текст:

    • command - команда бота (все равно будет обработана соответствующим ботом, будет удален только текст команды)
    • char1 - сообщение длиной в один или ноль символов, пробелы не считаются за символы
    • emoji - сообщение, которое содержит ТОЛЬКО символы эмодзи (любое число). Фильтр не соответствует сообщению, содержащему как эмодзи, так и текстовые символы.
    • emoji_spam - любое сообщение, содержащее текст И 4 или более символа эмодзи
    • custom_emoji - любое сообщение, содержащее premium emoji
    • bold - соответствует сообщению, если большая часть его содержимого отформатирована полужирным шрифтом
    • italic - соответствует сообщению, если большая часть его содержимого отформатирована курсивом
    • char250 - сообщение, содержащее более 250 символьных символов
    • char500 - сообщение, содержащее более 500 символьных символов
    • char1000 - сообщение, содержащее более 1000 символьных символов
    • hashtag - сообщение, содержащее хэштег
    • not_hashtag - сообщение, НЕ содержащее хэштега
    • text - любое текстовое сообщение (смайлики тоже текст)
    • cryptohash - адрес криптокошелька
    • uppercase - соответствует сообщению, длина которого превышает 30 символов, и большинство символов в верхнем регистре
    • number - соответствует сообщению, которое содержит число (да, просто любое число, например" 234234 "или" 1 ")
    • number9 - соответствует сообщению, которое содержит число, состоящее из 9 или более цифр
    • number11 - соответствует сообщению, которое содержит число, состоящее из 11 или более цифр
    • bank_card_number - соотвествует сообщению, которое содержит номер банковской карты
    • mixed_abc - соответствует сообщению, в котором есть слово, содержащее буквы различных алфавитов. На данный момент поддерживаются только русский и английский алфавиты
    • not_enru - соотвествует сообщению, в котором содержатся символы, отличные от пунктуации, пробелов, эмоджи, русского алфавита, английского алфавита.
  • Пользователи:

    • bot - любой бот, добавленный в чат, будет тут же удалён
    • bot_inviter - пользователь, который пригласил любого бота в чат, будет удалён из чата
    • new_user - если новый пользователь присоединяется к чату, он будет кикнут (не забанен)
    • nousername - новые пользователи без @username будут исключены из чата
    • sender_chat - сообщение, написанное от лица канала. Этот фильтр удаляет только сообщения из "чужих" каналов, фильтр не будет удалять сообщения из канала, который оцифиально привязан к чату.
    • user_premium - пользователи с premium аккаунтом не смогут войти в чат
  • Другие фильтры:

    • msg - любое видимое сообщение от пользователя. Также обратите внимание на модуль mute -- он разработан специально для удаление всех сообщений в чате в заданный период времени.
    • forwarded - сообщение переадресовано из любого другого места
    • button - сообщение, содержащее любую кнопку. Обычно это сообщение, отправленное через встроенного бота.
    • poll - опрос
    • contact - сообщение с карточкой контакта в Telegram
    • game - сообщение, содержащее телеграм-игру
    • inline - соответствует сообщениям, отправленным встроенным ботом (например, ботом @gif)
    • dice - одиночный смайлик, который отображается как анимация типа" Бросок кости ". Это игральные кости, дротики, футбольный мяч и т. Д.
    • location - сообщение с гео-позицией пользователя (карта)
    • msg_premium - сообщение от пользователя с premium аккаунтом
    • offline - сообщение опубликовано через механизм отложженных сообщений

Модуль spam

Система ботов tgdev анализирует все сообщения во всех чатах, где установлены боты tgdev, и автоматически определяет телеграм-аккаунты, рассылающие спам. Такие аккаунты заносятся в глобальный спам-список. С момента попадания телеграм-аккаунта в спам-список все сообщения, написанные этим аккаунтом, удаляются модулём spam в любом чате, где используется tgdev бот с активированным модулём spam.

В отличие от других модулей модуль spam активен по-умолчанию. Это значит, что при добавлении бота в чат и выдаче боту прав на удаление сообщений, бот начинает автоматически удалять спам. Если вам это не нужно, отключите модуль spam.

Если вы заметили неправильную работу модуля spam, пожалуйста, сообщите об этом в чат поддержки.

В веб-интерфейсе по адресу new.tgdev.io/manage/spam представлен суммарный поток сообщений, определённых как спам. Это аггрегированный поток сообщений из всех чатов, которыми вы управляете с помощью tgdev ботов.

Веб-админка

Веб-админка на данный момент является экспериментальной функцией и не содержит полноценный интерфейс управления модулями бота.

Для того, чтобы залогиниться в веб-админку, вам нужно написать в личные сообщения любому tgdev боту (см. список в начале документации) команду /tgdev auth. Бот отобразит вам кнопку. После нажатия на кнопку вы будете перенаправлены на сайт new.tgdev.io и автоматически залогинены под вашим Telegram аккаунтом.

В данный момент в веб-админке представлены следующие разделы:

  • new.tgdev.io/account -- информация о Telegram аккаунте, под которым вы залогинились в админку. Список групп, которые управляются ботами tgdev и в которых ваш аккаунт имеет права администратора. При нажатии на ссылку "logs" около названия группы, вы перейдёте в список из последних 100 административных действий, которые совершил бот в вашей группе т.е. вы увидите какие сообщения были удалены и каким именно модулем.
  • new.tgdev.io/manage/spam -- агрегированный поток сообщений, автоматически определённых как спам, из всех групп, которыми вы управляете.

Группа с топиками

В группах с топиками боты TgDev не различают, в каком топике было написано сообщение. Боты TgDev получают единый поток сообщений из всех топиков и могут удалять сообщения в соответствии с конфигурацией модулей, но уведомления шлют всегда в главный (#General) топик. Если в вашей группе отключен главный (#General) топик, то бот всё равно будет пытатся писать (безуспешно) уведомления в главный (#General) топик, то есть вы не увидите уведомления модулей об удалённых командах, а также не увидите ответы бота на административные команды, которые администраторы вводят в чат.