Привет, Хабр! Позвольте представиться: меня зовут Сергей Агальцов, и я "программист по жизни". Это значит, что я давно уже IT-менеджер, а вовсе не программист по профессии, но программирование использую постоянно, как в своей основной деятельности, так и как хобби. Как часто говорил один из моих бывших начальников — "Серёга! Ты опять скатился в программирование!" Правда, не могу сказать, что этим был сильно не доволен он или кто-то другой когда-либо.

После появления Bot API у мессенджера ТамТам, я как истинный, а значит ленивый программист, создал 2 библиотеки Python для работы с ним:

• open API клиента (далее — OAC) — изначально сгенерировал её при помощи OpenAPI Generator на основе схемы API, затем адаптировал с учётом особенностей генератора;
• оболочку для этого клиента — TamTamBot (далее — TTB), упрощающую работу с OAC.

Так появился некий ТамТам Python SDK.

Сделал это я в первую очередь "для себя, для души", но также предложил и комьюнити ТамТам при желании им воспользоваться. Но, как известно, ни одно доброе дело не остаётся безнаказанным — народ попросил написать обучающую статью. И вот я здесь с этой статьёй. В ней я расскажу, как разработать простого бота при помощи этих библиотек.

Задача

Разработать бот, предназначенный для упрощения действий разработчиков ботов. Бот должен работать в режиме перманентного опроса состояния bot-api (long polling). В этой статье бот будет обучен показывать внутренности пересылаемого ему сообщения, а также настроен в соответствие разработанной функциональности.

Подразумевается, что у читателя имеется установленный Python 3, git, подключенный к среде разработки PyCharm (среда разработки может быть и другой, но рассказ будет на основе PyCharm). Желательно понимание основ ООП.

Получение токена бота

Получение токена происходит через обращение к специализированному боту @PrimeBot

Находим этого бота в ТамТам, вводим команду /create и отвечаем на вопросы:

• Введите уникальное короткое имя бота латиницей — это юзернейм бота, по которому он будет доступен через @ или по ссылке вида https://tt.me/username. Особых ограничений на юзернейм нет. В частности, слово bot необязательно.
• Введите имя — это отображаемое имя бота. Здесь уже можно кириллицей.

Если всё введено корректно, то созданный бот будет добавлен в контакты и в ответ мы получим токен — последовательность символов вида: HDyDvomx6TfsXkgwfFCUY410fv-vbf4XVjr8JVSUu4c.

Первичная настройка

mkdir ttBotDevHelper

cd ttBotDevHelper/

git init

git submodule add https://github.com/asvbkr/openapi_client.git openapi_client
git submodule add https://github.com/asvbkr/TamTamBot.git TamTamBot

venv/
.idea/

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

*.log
*.log.*

.env
ttb.sqlite3

Запуск простейшего бота

Открываем файл ttBotDevHelper.py и пишем первые строки:

# -*- coding: UTF-8 -*-
from TamTamBot.TamTamBot import TamTamBot

class BotDevHelper(TamTamBot):
    pass

Здесь мы создаём класс своего бота, основываясь на классе TamTamBot.

PyCharm подсказывает, что класс BotDevHelper содержит абстрактные методы, которые необходимо имплементировать. Нажимаем Alt-Enter на названии класса, выбираем "Implement abstract methods", выбираем все методы (их 2), предложенные PyCharm и нажимаем ОК. В результате будут добавлены два пустых метода-свойства: token и description. Модифицируем получившийся код следующим образом:

# -*- coding: UTF-8 -*-
import os

from TamTamBot.TamTamBot import TamTamBot
from TamTamBot.utils.lng import set_use_django

class BotDevHelper(TamTamBot):
    @property
    def token(self):
        return os.environ.get('TT_BOT_API_TOKEN')

    @property
    def description(self):
        return 'Этот бот помогает в разработке и управлении ботами.\n\n'                'This bot is an helper in the development and management of bots.'

if __name__ == '__main__':
    set_use_django(False)
    BotDevHelper().polling()

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

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

Отмечу, что базовый класс TamTamBot предполагает использование веб-сервера django для работы в режиме вебхуков. Но сейчас задача проще, и django нам не требуется, о чём мы и сообщаем в строке set_use_django(False). Здесь для объекта нашего класса вызывается метод polling(), который и обеспечивает работу в нужном режиме.

Минимум необходимого сделан. Этот код уже вполне рабочий. Запустим его на выполнение. Для этого нажмём комбинацию клавиш Ctrl-Shift-F10.

Если Вы не добавляли переменную среды ранее, непосредственно в ОС, то при запуске произойдёт ошибка с сообщением "No access_token". Для её устранения настройте PyCharm на использование .env-файла.

TT_BOT_API_TOKEN=токен_нашего_бота

После запуска бота можно перейти в ТамТам, открыть диалог с нашим ботом и нажать кнопку "Начать". Бот сообщит информацию о своих скрытых суперспособностях. Это и означает, что бот работает. Пока бот работает в демо-режиме, в котором доступны 4 команды. Просто ознакомьтесь с ними.

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

Приём сообщения-источника и отправка ответного сообщения с внутренним представлением сообщения-источника

Перекроем метод receive_text(), управление которому передаётся при отправке текста в чат с ботом:

    def receive_text(self, update):
        res = self.msg.send_message(NewMessageBody(f'Ваше сообщение: {update.message}', link=update.link), user_id=update.user_id)
        return bool(res)

Объект update класса UpdateCmn, который передаётся в данный метод, содержит различную полезную информацию и, в частности, всё то, что нам сейчас необходимо:

• update.message — объект, содержащий само сообщение;
• update.link — готовая ответная ссылка на это сообщение;
• update.user_id — идентификатор пользователя, отправившего сообщение.

Для отправки сообщения от бота используем переменную self.msg, в которой содержится объект MessagesApi, реализовывающий функциональность, описанную в разделе messages описания API. Этот объект содержит нужный нам метод send_message(), который и обеспечивает отправку сообщений. По минимуму, в этот метод необходимо передать объект класса NewMessageBody и адресата — идентификатор пользователя, в нашем случае.

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

Перезапускаем нашего бота и проверяем в диалоге с ботом, что на любое наше сообщение бот формирует ответ, содержащий внутреннее представление объекта сообщения-источника.

Исходный код данного состояния см. здесь.

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

При разработке ботов зачастую требуется посмотреть внутреннее представление сообщения по одному или нескольким известным идентификаторам сообщений (message id — mid). Добавим такую функциональность нашему боту. Для этого, вначале, вынесем в отдельный метод функциональность вывода информации о внутреннем представлении сообщений:

    def view_messages(self, update, list_mid, link=None):
        res = False
        msgs = self.msg.get_messages(message_ids=list_mid)
        if msgs:
            for msg in msgs.messages:
                r = self.msg.send_message(NewMessageBody(f'Сообщение {msg.body.mid}:\n`{msg}`'[:NewMessageBody.MAX_BODY_LENGTH], link=link), user_id=update.user_id)
                res = res or r
        return res

В этот метод мы передаём список mid.

Для получения объектов сообщений мы используем метод self.msg.get_messages, возвращающий список объектов в свойстве messages.

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

Затем добавим метод, обрабатывающий команду. Назовём её vmp. В команду можно будет передать список mid через пробел.

ТТБ спроектирован таким образом, что обработчик команды должен создаваться как метод с именем cmd_handler_%s, где %s — имя команды. Т.е. для команды vmp метод будет называться cmd_handler_vmp. В обработчик команды передаётся объект класса UpdateCmn. Дополнительно, для команды он может содержать свойство cmd_args, в котором содержится словарь строк и слов в них, которые были введены вместе с командой

Код будет выглядеть так:

    def cmd_handler_vmp(self, update):
        res = None
        if not update.this_cmd_response:  # Это прямой вызов команды, а не текстовый ответ на команду
            if update.cmd_args:  # Если вместе с командой сразу переданы аргументы
                list_id = []
                parts = update.cmd_args.get('c_parts') or []
                if parts:
                    for line in parts:
                        for part in line:
                            list_id.append(str(part))
                if list_id:
                    res = self.view_messages(update, list_id, update.link)
        return bool(res)

Перезапускаем бот. Теперь, если в диалоге бота набрать команду вида: /vmp mid1 mid2 (mid'ы можно взять их предыдущих проверок), то в ответ мы получим два сообщения с внутренним представлением объектов сообщений-источников, по каждому из переданных mid.

Исходный код данного состояния см. здесь.

Модификация команды бота для работы с текстовым ответом

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

Но что делать, если мы хотим увидеть информацию об оригинальном сообщении? В этом случае нужно брать mid из пересланного сообщения.

Для реализации этого режима модифицируем команду vmp таким образом, чтобы при её вызове без параметров она ожидала пересылки сообщения, а после этого брала mid пересланного сообщения и выводила информацию о нём.

(!) Для корректной работы данного функционала, боту должно быть предоставлено разрешение на чтение из канала/чата источника.

Код команды модифицируем следующим образом:

    def cmd_handler_vmp(self, update):
        res = None
        if not update.this_cmd_response:  # Это прямой вызов команды, а не текстовый ответ на команду
            if update.cmd_args:  # Если вместе с командой сразу переданы аргументы
                list_id = []
                parts = update.cmd_args.get('c_parts') or []
                if parts:
                    for line in parts:
                        for part in line:
                            list_id.append(str(part))
                if list_id:
                    res = self.view_messages(update, list_id, update.link)
            else:  # Вывод запроса для ожидания ответа
                self.msg.send_message(NewMessageBody(f'Перешлите *одно* сообщение канала/чата для показа его свойств:'), user_id=update.user_id)
                update.required_cmd_response = True  # Сообщаем о необходимости ожидания текстового ответа
        else:  # Текстовый ответ команде
            message = update.message
            link = message.link  # Доступ к пересланному сообщению через свойство link
            # Проверим - пересылка ли это.
            if link and link.type == MessageLinkType.FORWARD:
                res = self.view_messages(update, [link.message.mid], update.link)
            else:
                # Выведем сообщение об ошибке и сообщим в коде возврата, что команда не отработала.
                self.msg.send_message(NewMessageBody(f'Ошибка. Необходимо *переслать* сообщение из канала/чата. Повторите, пожалуйста.'), user_id=update.user_id)
                return False

        return bool(res)

А т.к. при таком подходе увеличивается риск из-за отсутствия доступа к сообщениям, то в метод view_messages() добавим проверку на соответствие количества запрошенных/полученных сообщений:

    def view_messages(self, update, list_mid, link=None):
        res = False
        msgs = self.msg.get_messages(message_ids=list_mid)
        if msgs:
            # Сравнение количества переданных mid с количеством полученных сообщений
            if len(msgs.messages) < len(list_mid):
                self.msg.send_message(NewMessageBody(
                    f'Не удалось получить все запрошенные сообщения. Проверьте доступ бота @{self.username} к каналам/чатам этих сообщений.', link=update.link
                ), user_id=update.user_id)
                return False
            else:
                for msg in msgs.messages:
                    r = self.msg.send_message(NewMessageBody(f'Сообщение {msg.body.mid}:\n`{msg}`'[:NewMessageBody.MAX_BODY_LENGTH], link=link), user_id=update.user_id)
                    res = res or r
        return res

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

Настройка свойств бота

Теперь осталось навести лоск. Перекроем свойство about, возвращающее текст, который бот выводит при начале работы с ним, а также по команде /start.

    @property
    def about(self):
        return 'Этот бот помогает в разработке и управлении ботами.'

Перекроем метод get_commands(), возвращающий список команд нашего бота, отображающийся в диалоге с ботом.

    def get_commands(self):
        # type: () -> [BotCommand]
        commands = [
            BotCommand('start', 'о боте'),
            BotCommand('menu', 'показать меню'),
            BotCommand('vmp', 'показать свойства сообщения'),
        ]
        return commands

Перекроем свойство main_menu_buttons, возвращающее список кнопок главного меню, вызываемого по команде /menu.

    def main_menu_buttons(self):
        # type: () -> []
        buttons = [
            # Кнопка будет выведена цветом по умолчанию - серым
            [CallbackButtonCmd('О боте', 'start')],
            # Кнопка будет выведена цветом для позитивных действий - синим. Также есть негативная - красная
            [CallbackButtonCmd('Показать свойства сообщения', 'vmp', intent=Intent.POSITIVE)],
        ]

        return buttons

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

Исходный код данного состояния см. здесь.

Работающего бота @devhelpbot можно посмотреть здесь.

На этом, пока, всё. Если тема заинтересовала, то в следующих статьях могу рассмотреть дальнейшее развитие бота. Например, добавление кастомных кнопок (в частности Да/Нет) и их обработку, отсылку различного вида контента (файлы, фото и пр.), работа в режиме webhook и т.п.

Кстати, оперативно вопросы можно задать в специальном чате. Туда же направляйте и предложения/идеи.