/AutoPostTelegramBot

Проект создан для более удобного управления каналами в Телеграме

Primary LanguageKotlinApache License 2.0Apache-2.0

БОТ ЗААРХИВИРОВАН И НЕ ЯВЛЯЕТСЯ ДЕЕСПОСОБНЫМ ВВИДУ ОБНОВЛЕНИЙ TELEGRAM BOT API. ВЫ МОЖЕТЕ ИСПОЛЬЗОВАТЬ PlaguPoster КОТОРЫЙ ИМЕЕТ ТОТ ЖЕ И ДАЖЕ БОЛЕЕ ШИРОКИЙ ФУНКЦИОНАЛ

Auto Post Telegram Bot

Download Build Status

Get automatic notifications about new "AutoPostTelegramBot" versions

Как начать использовать?

Если необходимо самостоятельно собрать проект, можно воспользоваться простой инструкцией:

  1. Скачать проект с Github
  2. Сделать ./gradlew исполняемым (chmod 455 ./gradlew для *nix)
  3. Выполнить ./gradlew build

В зависимости от дистрибутива и целей, инструкция запуска будет несколько отличаться:

  • В случае самостоятельной сборки (а также в случае скачивания архива с jenkins страницы)
    1. Разархивировать в директорию, где будет находиться бот
    2. Найти исполнительный файл в папке $WORK_DIRECTORY/AutoPostTelegramBot-$version/bin/ (для Windows файл имеет расширение .bat)
    3. Запустите из консоли соответствующий файл, передав первым аргументом путь до JSON конфига
  • В случае использования проекта как библиотеки желательно указать как главный класс com.github.insanusmokrassar.AutoPostTelegramBot.LaunchKt
  • В случае запуска в Intellij Idea рекомендуется
    • Использовать шаблон Jar Application
    • Как аргумент устанавливать путь до JSON конфига
    • Путь до Jar будет выглядеть как $PROJECT_DIR/build/libs/$FILENAME.jar
    • Перед сборкой как запускать задачу gradle ./gradlew clean build
  1. Profit

Возможности

Что бот может?

Если кратко, назначением бота является автоматизация и нормализация создания и публикации постов в каком-либо чате/канале. Под постом в данном случае понимается совокупность сообщений, которые должны быть опубликованы одновременно. Публикация происходит из чата/канала, выбранного как sourceChat путем выставления соответствующего sourceChatId.

A little bit deep или капелька взгляда изнутри

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

База

Данный бот в основе своей имеет абсолютный минимум для запуска:

  • Пост - совокупность сообщений и сообщения-уведомлений о регистрации
  • Базовая БД хранится в двух публичных классах, имеющих coroutine-каналы для подписки
  • Класс запуска имеет coroutine-каналы для подписки на сообщения, приходящие к боту
  • Система плагинов

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

Плагины

Любой плагин наследуется от класса Plugin

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

Остальное

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

Формат времени

После длительного тестирования и проверок было решено добавить стандартизированную работу с временем, которая позволила бы разработчикам плагинов не писать лишний и повторяющийся код, а пользователям (администраторам каналов и групп) - не забивать голову лишними форматами конфигураций. Итак, что из себя представляет простейший формат времени?

  • Время: [часы:]минуты[:секунды[.миллисекунды]] - стоит учесть, что если вы хотите указать только секунды, следует использовать запись 00:00:секунды
  • Дата: [[год.]месяц.]день - то есть верным будет указание просто числа 15, если вы имеете ввиду 15 день месяца. В зависимости от контекста это может быть ближайший 15 день месяца, то есть если сегодня 16 число - ближайшее 15 число будет в следующем месяце. NOTE: НЕ ИСПОЛЬЗУЕТСЯ БЕЗ УКАЗАНИЯ ВРЕМЕНИ (см. Дата и время)
  • Дата и время: [дата ]время - то есть в большинстве случаев (если не всегда) выбудете обязаны написать в качестве времени хотя бы 00, что будет расценено как полуночь или 00 минут каждого часа (см. последовательность времени) (стоит понимать, что дата тут необязательный параметр)
  • Пара даты и времени: Дата и время-Дата и время - используется для указания пары даты-времени или некоторого промежутка (см. последовательность времени)
  • Последовательность времени: Дата и время-Дата и время [step ]Дата и время - тут стоит сказать больше. Когда вы планируете некоторое действие повторять (например, публикация по времени) - гораздо удобней использовать некоторые hotkeys. Тут мы используем третий параметр дата-время, чтобы указать задержку между датами. Параметр step не обязателен, но он позволит быть уверенными, что последовательность будет построена корректно и пробел не будет распознан как разделитель даты-времени.

Примеры:

  • 12:30-12:40 01 - создаёт последовательность из времени
    • 12:30
    • 12:31
    • 12:32
    • ...
    • 12:39
  • 10-20 step 5 - без step промежуток 5 будет распознан как значение минут. Кроме того, если вы будете использовать этот формат для задания последовательности событий в будущем, поскольку вы не указали часы - считается, что это вольный параметр*. В таком случае при необходимости можно получить следующую последовательность:
    • 00:10
    • 00:15
    • 01:10
    • 01:15
    • ...
  • 15 12:35 - фактически, будет распознаваться как ближайшее 15 число, 12 часов 35 минут

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

Плагины, включенные в базовый пакет

  • BasePlugin - предоставляет доступ к основному функционалу и в большинстве случаев обязателен к подключению:

    [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.base.BasePlugin",
  {}
]

    Включает следующий функционал:

    • /startPost используется в паре с /fixPost, сообщения между ними будут прикреплены к одному посту. Можно не использовать для галерей (медиагрупп), поскольку такие группы определяются автоматически в один пост. Пример (каждый пункт - отдельное сообщение):
      1. /startPost
      2. Тут какой-то текст
      3. Картиночка
      4. Еще что-то
      5. /fixPost
      6. Далее вас оповестят, что серия сообщений закреплена за одним постом и будет опубликована. Записи публикуются не по состоянию на момент создания, а по состоянию на момент перед публикацией. Кроме того, учтите, что бот не сможет удалять сообщения из постов, если они были отправлены более двух дней назад (специфика Telegram) - бот об этом оповестит в канале с логами и скажет, что он не может удалить (приведет еще причину, если вдруг там чего странного).
    • /deletePost - используйте через reply сообщения с текстом Post registered, будет удален пост вместе с его сообщениями. Важно: /startPost//fixPost таким образом не удаляются - их нужно чистить вручную.
    • /renewRegistered или /renewRegisteredMessage - при реплае одного из сообщений поста удаляет старое сообщение "Post registered" (если оно есть) и отправляет новое

  • PostPublisher - предоставляет возможность публиковать посты без необходимости вручную писать форвард поста. Данный плагин содержит интерфейс Publisher, рекомендуемый для имплементации в случае, если вы хотите создать свою реализацию публикатора. Подключение плагина:

    {
    "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.publishers.PostPublisher",
    {}
}

    Предоставляет:

    • /publishPost - команда, используемая для немедленной публикации пост(а)(ов). Может использоваться в трех вариантах:
      • /publishPost - публикуется один пост из тех, что выбираются выбиралкой из конфига
      • /publishPost [число] - публикается какое-то число постов, выбранных инстансом Chooser из конфига. Стоит учесть, что при первом совпадении между уже выбранными командой и выданным ей списком из Chooser команда прекращает выборку и публикует то, что уже выбрано. Само собой, требуется подключение одного из Chooser плагинов.
      • /publishPost с reply какого-то из постов (как для deletePost) - публикует только выбранный пост

  • RatingPlugin - плагин для подключения рейтингов. Позволяет команде голосовать за/против определенные посты и на основании голосов выбирать посты для публикации. Подключение:

    [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.rating.RatingPlugin",
  {}
]

    Подключение предоставляет:

    • Возможность командой оценивать посты
    • Подключение большого числа плагинов, в том числе
      • Многие Chooser плагины
      • GarbageCollector
      • PostPublisher - публикация по рейтингу
    • /mostRated - выводит список самых топовых на данный момент постов. Если ваша планерка - не публичный канал, топовые посты будут переотправлены. Обычно можно нажать на название после forwarded from и вам откроется сам пост.
    • /availableRatings - выводит список пар "рейтинг" - "число постов", зарегестрированных в системе
    • /enableRating - включение рейтинга для поста
    • /disableRating - выключение рейтинга для поста

  • Chooser'ы - набор классов, имплементирующих интерфейс Chooser, по-умолчанию используемый во всех других плагинах для выбора списка постов для публикации. Все плагин Chooser (за исключением None) требуют подключения RatingPlugin. Доступные плагины-Chooser'ы по-умолчанию:

    • SmartChooser - наиболее гибкий из представленных по-умолчанию Chooser реализаций. Публикует в разное время разные посты в зависимости от настроек. Подключение: 
      [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.choosers.SmartChooser",
  {
    "times": [
      {
        "minRate": -2,
        "maxRate": 1,
        "sort": "ascend|descend|random",
        "time": "16:00-17:00",
        "times": [
            "16:00-17:00",
            "20:00-21:00"
        ],
        "timeOffset": "+03:00",
        "minAge": 86400000
      }
    ]
  }
]
      имеет следующую структуру для параметра params:
      • times - список временнЫх настроек для выборщика, каждый объект которого содержит следующие параметры:
        • minRate - минимальный рейтинг для попадания в список кандидатов на выбор, если не указано - считается, что минимума нет
        • maxRate - максимальный рейтинг для попадания в список кандидатов на выбор, если не указано - считается, что максимума нет
        • sort - режим сортировки кандидатов на выборку
        • time - время в стандартном формате (или см. ниже)
        • times - массив времени в стандартном формате (учитывается в первую очередь)
        • count - число постов, производимых за раз
        • minAge - число в миллисекундах, отвечающее за минимальный возраст поста попадания в кандидаты для выборки
        • maxAge - число в миллисекундах, отвечающее за максимальный возраст поста попадания в кандидаты для выборки
    • MostRated - выбирает всегда самые старые из самых популярных постов. Подключение: 
      [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.choosers.MostRatedChooser",
  {}
]
    • MostRatedRandomly - выбирает случайные из самых популярных постов. Подключение: 
      [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.choosers.MostRatedRandomChooser",
  {}
]
    • None - всегда возвращает пустой список постов. Подключение: 
      [
  "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.choosers.NoneChooser",
  {}
]

  • TimerTrigger - предоставляет возможность осуществлять автоматическую публикацию раз в строго определённое время. Для работы требует подключенные Chooser и Publisher плагины. В момент триггера спросит у Chooser посты для публикации и передаст их Publisher. Как параметр принимает time принимает стандартный формат времени. Подключение:

        [
      "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.triggers.TimerTriggerStrategy",
      {
        "time": "00:30-00:30 01:00"
      }
    ]

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

  • SchedulerPlugin - позволяет ставить посты на публикацию в определенное время (в том числе на конкретную дату). Добавляет команды:

    • /setPublishTime (time format) - установка таймера на пост
    • /getPublishSchedule[ [число]|[time пара]] - пересылает несколько постов выставленных на таймер. Если указано число - будут выбранны ближайшие записи в количестве, указанном в параметре. Если указана пара времени в стандартном формате - даты будут взяты по две (нужно помнить, что при указании периода будет создана последовательность дата-время) и для каждой найдены все публикации на таймере
    • /disableSchedulePublish - исключает из публикации по таймеру пост

    Подключение:

        [
      "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.scheduler.SchedulerPlugin"
    ]

  • GarbageCollector - как следует из названия, собирает мусор. Если точнее, удаляет записи с рейтингом ниже установленного минимума. Подключение:

        [
      "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.GarbageCollector",
      {
        "minimalRate": -2,
        "skipTime": "23:59",
        "manualCheckTime": "00:00-00:00 03:00"
      }
    ]

    Отсутствие manualCheckTime в настройках отключит проверку по времени и будет реагировать только на события изменений в плагине RatingPlugin. skipTime позволит включить режим неприкосновенности на время с момента поста - GarbageCollector будет игнорировать пост пока пост попадает в промежутки времени этого параметра. Например выше указано 23:59 - это значит, что пост будет неприкосновенен в течение 23 часов и 59 минут

  • BotLogger - по-факту, инициализирует LogHandler через вызов initHandler в момент инициализации плагина. Подключение:

        [
      "com.github.insanusmokrassar.AutoPostTelegramBot.plugins.BotLogger",
      {
        "config": // опциональное поле, заполняемое как commonBot в корне конфига
      }
    ]

Секции конфигурации

В корне конфигурации лежат следующие параметры (учтите, что ChatId - именно id, не username):

  • targetChatId - идентификатор чата, куда в итоге будут отправляться посты; число
  • sourceChatId - идентификатор чата, откуда в итоге будут браться посты; число
  • logsChatId - идентификатор чата, куда будут отправляться системные сообщения, по-умолчанию будет равен sourceChatId; число
  • commonBot - настройка для общего бота, используемого остальными плагинами и частями системы по-умолчанию
    • botToken - токен Telegram Bot для доступа к API вида 123456789:ABCDEFGHIGKLMNOPQRSTUVWXYZabcdefghi
    • clientConfig - конфигурация клиента для доступа в интернет ботом
      • proxy - объект настройки Socks5 прокси. Достаточно указать {}, если вы используете shadowsocks, запущенный в вашей системе
        • host - url прокси, по-умолчанию - localhost
        • port - порт прокси, по-умолчанию - 1080
        • username - имя пользователя для доступа к прокси через авторизацию
        • password - пароль для доступа к прокси через авторизацию
      • connectTimeout - задержка для подключения, по-умолчанию: 0 (нет ограничения)
      • writeTimeout - задержка для отправки данных, по-умолчанию: 0 (нет ограничения)
      • readTimeout - задержка для чтения данных, по-умолчанию: 0 (нет ограничения)
      • debug - настройка для вывода отладочной информации по запросам бота контроля действий бота
    • webhookConfig - конфигурация для установки вебхука (опциональное поле)
      • url - URL адрес, на который должны приходить обновления
      • port - внутренний порт, использованный для прокидывания через reverse proxy
      • certificatePath - путь до публичного файла сертификата
      • maxConnections - максимальное число подключений (1 - 100) (опциональное поле)
  • databaseConfig - объект настройки базы данных. Включает следующие поля:
    • username - имя пользователя для доступа к базе данных
    • password - пароль для доступа к базе данных
    • url - путь для доступа к базе данных. Например, jdbc:h2:mem:test;DB_CLOSE_DELAY=-1 может использоваться для базы данных "на раз", то есть, в памяти с использованием базы данных h2
    • driver - classname драйвера базы данных. Например, org.h2.Driver для использования драйвера h2
  • plugins - список подключенных плагинов. Каждый плагин имеет следующие поля:
    • classname - полное пакетное имя класса плагина. Например, com.github.insanusmokrassar.AutoPostTelegramBot.plugins.triggers.TimerTriggerStrategy для подключения плагина триггеринга постов по времени
    • params - объект настроек плагина.

Заметки

Бот игнорирует сообщения, начинающиеся с / и не являющиеся известной ему командой. Это значит, что какие-то объявления можно писать, начиная сообщение со знака /. Учтите, что если вам понадобится закрепить такое сообщение - сообщение о закреплении будет являться полноценным сообщением и будет отмечено как пост. В таком случае его следует удалить как пост - через команду /deletePost.

Послесловие

Так или иначе, жду отзывы и предложения в Telegram и по email.