Архитектура бота для Telegram

В статье пойдет речь о запуске платформы на базе Telegram бота, предназначенной для взаимодействия с самыми разными сервисами, например с GitHub и Яндекс.Метрикой.

Платформа позволяет создавать плагины для работы с каждым из них. Вы сможете в один клик настроить оповещения о коммитах, pull-реквестах, закрытии issues из каждого репозитория в нужный чат и установить внешний вид этих оповещений. Вы даже можете попросить бота присылать вам свежую статистику из Яндекс.Метрики в удобное для вас время. Мы в команде CodeX используем данное решение уже несколько месяцев и не представляем себе, как можно было работать без этого.

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

Облачное решение

Просто добавьте @codex_bot к своему рабочему чату и введите сообщение:

/help@codex_bot

Запуск бота на своем сервере

Для запуска CodeX.bot вам потребуется выполнить следующие действия:

установить дополнительные библиотеки для языка Python
клонировать наш репозиторий с кодом бота
зарегистрировать нового бота в Telegram
отредактировать файл конфигурации

Установка дополнительных библиотек

CodeX.bot написан на языке Python с использованием некоторых дополнительных библиотек. Вам нужно установить их, прежде чем начать работу:

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

Клонировать репозиторий CodeX.bot можно выполнив команду:

git clone [email protected]:codex-team/codex.bot.git

Для работы системы вам понадобится создать Telegram бота. Просто следуйте инструкции из статьи или официального руководства.

Конфигурация

Теперь вам необходимо настроить конфигурацию системы. Для этого переименуйте директорию local.sample в local и отредактируйте содержимое файла config.py в соответствии с вашими предпочтениями:

SERVER_HOST - адрес вашего сервера. Если вы пользуетесь прокси ngrok, он будет выглядеть приблизительно так: 'http://9b812f5d.ngrok.io'.

LOCAL_SERVER_PORT - порт, на котором будет запущен ваш локальный сервер.

LOGS_FILENAME - адрес файла для логов. По умолчанию равен 'logs/logs.log'.

SSL_CERTIFICATE - содержимое SSL сертификата сервера. По уполчанию равен None.

API_TOKEN - токен вашего Telegram бота через которого будет работать система.

TELEGRAM_CALLBACK_URL - адрес, по которому CodeX.bot будет обрабатывать все сообщения от Telegram. Например: 'https://9b812f5d.ngrok.io/telegramcallback'.

Установка Telegram Webhook

Telegram позволяет установить webhook для ботов. Это нужно для того, чтобы при каждом сообщении, отправленном в чат с ботом, Telegram устанавливал соединение с вашим сервером и передавал ему JSON с текстом и сервисной информацией. Поскольку Telegram работает только по протоколу HTTPS, вам понадобится SSL сертификат. Если у вас есть доверенный сертификат, то ничего дополнительно настраивать не придется, в случае использования самоподписанного сертификата, его нужно будет отправить при установке вебхука.

Сгенерировать сертификат можно следующей командой:

openssl req -new -x509 -nodes -newkey rsa:1024 -keyout server.key -out server.crt

Далее, openssl предложит вам заполнить несколько полей информации, важно указать поле FQDN равное адресу хоста-callback’а.

Для установки вебхука можно воспользоваться пакетом python-telegram-bot для Python.

import telegram

TOKEN = ''
HOST = '' # Параметр FQDN сертификата должен совпадать с данным адресом
PORT = 8443
CERT = 'path/to/ssl/server.crt'

bot = telegram.Bot(TOKEN)
bot.setWebhook(webhook_url='https://%s:%s/%s' % (HOST, PORT, TOKEN), certificate=open(CERT, 'rb'))

К счастью, CodeX.bot сделает установку вебхука за вас, если в настройках ему передать соответствующий параметр. Например:

SSL_CERTIFICATE = open("/path/to/ssl/server.crt", 'rb')

Структура файловой системы

В файле local/db.py содержатся настройки базы данных, где CodeX.bot хранит всю необходимую информацию. По умолчанию у вас будет использоваться SQLite.

В файле components/core.py вы можете найти несколько глобальных функций, которые используются всеми компонентами системы:

send_to_chat - отправка сообщений в Telegram чат.
generate_hash - генерация уникальных идентификаторов для пользователей и чатов.
bgcolors - для вывода отладочной информации в консоль.

В файле main.py содержится код запуска системы. Запуск выполняется в следующем порядке:

Подключение файла вывода логов.
Установка вашего сервера в качестве webhook для Telegram бота.
Загрузка плагинов, описанных в глобальной конфигурации.
Запуск веб-сервера, получающего оповещения от Telegram бота.

В файле modules/core/server.py находится код веб-сервера, который обрабатывает сообщения от Telegram и передает их нужным плагинам, вызывая у них метод telegram_command:

@app.route('/telegramcallback', methods=['POST'])
def t_webhook_route_handler():
    try:
        update = telegram.update.Update.de_json(request.get_json(force=True))
        for plugin in PLUGINS:
            plugin.telegram_command(update.message)

    except Exception as e:
        logging.warning("Message process error: [%s]" % e)

Разработчик плагина сам устанавливает какие команды обрабатывать. Например, модуль ответственный за Github оповещения принимает команду /github_start примерно так:

def telegram_command(self, message):
    if '/github_start' in message.text:
        ...

Плагин может самостоятельно принимать оповещения от сторонних сервисов в специальном методе set_rules:

def __init__(self):
        self.module_name = 'github'
        self.uri_prefix = '/github'

  def set_rules(self, app):
        app.add_url_rule('%s/test' % self.uri_prefix,
            '%s_test' % self.module_name,
            test)
        app.add_url_rule('%s/' % self.uri_prefix,
            '%s_callback' % self.module_name,
            callback,
            methods=["POST"])

Подробнее работу основных плагинов рассмотрим в следующей статье.