Привет, Хабр! Позвольте представиться: меня зовут Сергей Агальцов, и я "программист по жизни". Это значит, что я давно уже IT-менеджер, а вовсе не программист по профессии, но программирование использую постоянно, как в своей основной деятельности, так и как хобби. Как часто говорил один из моих бывших начальников — "Серёга! Ты опять скатился в программирование!" Правда, не могу сказать, что этим был сильно не доволен он или кто-то другой когда-либо. После появления Bot API у мессенджера ТамТам, я как истинный, а значит ленивый программист, создал 2 библиотеки Python для работы с ним: Так появился некий ТамТам Python SDK. Сделал это я в первую очередь "для себя, для души", но также предложил и комьюнити ТамТам при желании им воспользоваться. Но, как известно, ни одно доброе дело не остаётся безнаказанным — народ попросил написать обучающую статью. И вот я здесь с этой статьёй. В ней я расскажу, как разработать простого бота при помощи этих библиотек. Разработать бот, предназначенный для упрощения действий разработчиков ботов. Бот должен работать в режиме перманентного опроса состояния bot-api (long polling). В этой статье бот будет обучен показывать внутренности пересылаемого ему сообщения, а также настроен в соответствие разработанной функциональности. Подразумевается, что у читателя имеется установленный Python 3, git, подключенный к среде разработки PyCharm (среда разработки может быть и другой, но рассказ будет на основе PyCharm). Желательно понимание основ ООП. Получение токена происходит через обращение к специализированному боту @PrimeBot Находим этого бота в ТамТам, вводим команду /create и отвечаем на вопросы: Если всё введено корректно, то созданный бот будет добавлен в контакты и в ответ мы получим токен — последовательность символов вида: HDyDvomx6TfsXkgwfFCUY410fv-vbf4XVjr8JVSUu4c. Создаём каталог: Переходим в него: Инициализируем хранилище git: Качаем необходимые библиотеки, добавляя их как подмодули git: Открываем созданный каталог в PyCharm (например из проводника по контекстному меню "Open Folder as PyCharm project") и создаём файл, который и будет содержать наш бот — File/New/Python file. В появившемся диалоге вводим имя — ttBotDevHelper, и отвечаем положительно на вопрос о добавлении в git. Теперь нужно создать виртуальную среду для нашего проекта. Для создания виртуальной среды выбираем File/Settings и на закладке проекта выбираем подраздел Project Interpreter. Далее, справа нажимаем на иконку шестерёнки и выбираем Add:  PyCharm предложит свой вариант размещения.  Имеет смысл с ним согласиться. После создания виртуальной среды откроется предыдущий экран, но на нём уже будет информация о созданной среде. На этом экране необходимо установить необходимые пакеты, нажимая справа иконку с "+" и вводя имена пакетов: Затем добавляем к проекту файл .gitignore, исключающий файлы, не требующиеся в git, со следующим содержимым: Добавим переменную среды с именем TT_BOT_API_TOKEN, в которой укажем значение токена нашего бота, полученного от https://tt.me/primebot и перезапустим PyCharm. (!) Вместо добавления переменной среды непосредственно в окружение ОС, в PyCharm оптимально использовать специальный файл .env. Его настройка будет рассмотрена ниже. Поздравляю, теперь можно приступать к самому интересному — написанию своего бота. Открываем файл ttBotDevHelper.py и пишем первые строки: Здесь мы создаём класс своего бота, основываясь на классе TamTamBot. PyCharm подсказывает, что класс BotDevHelper содержит абстрактные методы, которые необходимо имплементировать. Нажимаем Alt-Enter на названии класса, выбираем "Implement abstract methods", выбираем все методы (их 2), предложенные PyCharm и нажимаем ОК. В результате будут добавлены два пустых метода-свойства: token и description. Модифицируем получившийся код следующим образом: Свойство token возвращает токен нашего бота, значение которого берётся из переменной окружения TT_BOT_API_TOKEN. Свойство description возвращает расширенное описание нашего бота, которое будет показываться пользователям. Код в конце файла необходим для запуска нашего бота в режиме опроса состояния. Отмечу, что базовый класс TamTamBot предполагает использование веб-сервера django для работы в режиме вебхуков. Но сейчас задача проще, и django нам не требуется, о чём мы и сообщаем в строке set_use_django(False). Здесь для объекта нашего класса вызывается метод polling(), который и обеспечивает работу в нужном режиме. Минимум необходимого сделан. Этот код уже вполне рабочий. Запустим его на выполнение. Для этого нажмём комбинацию клавиш Ctrl-Shift-F10. Если Вы не добавляли переменную среды ранее, непосредственно в ОС, то при запуске произойдёт ошибка с сообщением "No access_token". Для её устранения настройте PyCharm на использование .env-файла. Создайте текстовый файл .env. Его содержимое в нашем случае должно быть следующим: Теперь нужно его подключить к конфигурации запуска в PyCharm: Выбираем Run/Edit configuration и на закладке EnvFile подключаем наш .env-файл:  После чего нажимаем Apply. После запуска бота можно перейти в ТамТам, открыть диалог с нашим ботом и нажать кнопку "Начать". Бот сообщит информацию о своих скрытых суперспособностях. Это и означает, что бот работает. Пока бот работает в демо-режиме, в котором доступны 4 команды. Просто ознакомьтесь с ними. Несмотря на ярко выраженное мнение бота о своей крутости, он же робко намекает и на то, что пока ничего не умеет. Научить его всему необходимому для завоевания мира и является нашей задачей. Перекроем метод receive_text(), управление которому передаётся при отправке текста в чат с ботом: Объект update класса UpdateCmn, который передаётся в данный метод, содержит различную полезную информацию и, в частности, всё то, что нам сейчас необходимо: Для отправки сообщения от бота используем переменную self.msg, в которой содержится объект MessagesApi, реализовывающий функциональность, описанную в разделе messages описания API. Этот объект содержит нужный нам метод send_message(), который и обеспечивает отправку сообщений. По минимуму, в этот метод необходимо передать объект класса NewMessageBody и адресата — идентификатор пользователя, в нашем случае. В свою очередь, объект класса NewMessageBody в данном случае создаётся посредством передачи текстового представления объекта сообщения-источника и ответной ссылки на сообшение-источник. Перезапускаем нашего бота и проверяем в диалоге с ботом, что на любое наше сообщение бот формирует ответ, содержащий внутреннее представление объекта сообщения-источника. Исходный код данного состояния см. здесь. При разработке ботов зачастую требуется посмотреть внутреннее представление сообщения по одному или нескольким известным идентификаторам сообщений (message id — mid). Добавим такую функциональность нашему боту. Для этого, вначале, вынесем в отдельный метод функциональность вывода информации о внутреннем представлении сообщений: В этот метод мы передаём список mid. Для получения объектов сообщений мы используем метод self.msg.get_messages, возвращающий список объектов в свойстве messages. Далее, текстовое представление каждого из полученных сообщений отправляем в наш диалог отдельными сообщениями. Чтобы избежать ошибки, текст формируемого сообщения обрезается по константе максимальной длины сообщения — NewMessageBody.MAX_BODY_LENGTH. Затем добавим метод, обрабатывающий команду. Назовём её vmp. В команду можно будет передать список mid через пробел. ТТБ спроектирован таким образом, что обработчик команды должен создаваться как метод с именем cmd_handler_%s, где %s — имя команды. Т.е. для команды vmp метод будет называться cmd_handler_vmp. В обработчик команды передаётся объект класса UpdateCmn. Дополнительно, для команды он может содержать свойство cmd_args, в котором содержится словарь строк и слов в них, которые были введены вместе с командой  Код будет выглядеть так: Перезапускаем бот. Теперь, если в диалоге бота набрать команду вида: /vmp mid1 mid2 (mid'ы можно взять их предыдущих проверок), то в ответ мы получим два сообщения с внутренним представлением объектов сообщений-источников, по каждому из переданных mid. Исходный код данного состояния см. здесь. Также можно попробовать переслать сообщение из другого канала/чата. Но в этом случае будет показано только то, что содержится в сообщении-источнике, находящемся в диалоге с ботом. В частности, при пересылке сообщения не сохраняется информация о кнопках. Но что делать, если мы хотим увидеть информацию об оригинальном сообщении? В этом случае нужно брать mid из пересланного сообщения. Для реализации этого режима модифицируем команду vmp таким образом, чтобы при её вызове без параметров она ожидала пересылки сообщения, а после этого брала mid пересланного сообщения и выводила информацию о нём.  (!) Для корректной работы данного функционала, боту должно быть предоставлено разрешение на чтение из канала/чата источника. Код команды модифицируем следующим образом: А т.к. при таком подходе увеличивается риск из-за отсутствия доступа к сообщениям, то в метод view_messages() добавим проверку на соответствие количества запрошенных/полученных сообщений: Перезапускаем бот, даём команду /vmp и после вывода приглашения о необходимости пересылки, пересылаем сообщение из канала/чата. При наличии у бота прав на чтение сообщений в этом канале/чате, будет выведено текстовое представление объекта пересланного сообшения. Если доступа нет, то бот сообщит о возможной проблеме и будет ожидать пересылки из корректного источника. Теперь осталось навести лоск. Перекроем свойство about, возвращающее текст, который бот выводит при начале работы с ним, а также по команде /start. Перекроем метод get_commands(), возвращающий список команд нашего бота, отображающийся в диалоге с ботом. Перекроем свойство main_menu_buttons, возвращающее список кнопок главного меню, вызываемого по команде /menu. Перезапускаем бот, убеждаемся что всё в порядке. Поздравляю, Ваш первый бот создан и, несмотря на некоторую игрушечность, обладает вполне востребованной функциональностью. Исходный код данного состояния см. здесь. Работающего бота @devhelpbot можно посмотреть здесь. На этом, пока, всё. Если тема заинтересовала, то в следующих статьях могу рассмотреть дальнейшее развитие бота. Например, добавление кастомных кнопок (в частности Да/Нет) и их обработку, отсылку различного вида контента (файлы, фото и пр.), работа в режиме webhook и т.п. Кстати, оперативно вопросы можно задать в специальном чате. Туда же направляйте и предложения/идеи. Программист-по-жизни