botapitamtam

Попытка создать набор простых инструментов для написания ботов на базе API мессенджера TamTam. Набор содержит базовый функционал взаимодействия бота с пользователями и предназначен для начинающих программистов. Синтаксис методов позволяет легко их модифицировать или создавать на их базе новые методы используя официальную документацию https://dev.tamtam.chat/ .

Примеры реализации ботов с использованем библиотеки:

https://github.com/registriren/filelink

https://github.com/registriren/translatebot

Чат для обсуждения вопросов, связанных с работой библиотеки https://tt.me/botapitamtam

Принцип взаимодействия с библиотекой:

1. Методы, которые начинаются с get_ получают события, произошедшие с ботом (написанные или пересланные сообщения, результат нажатия кнопок, вложения и т.д.).
2. Методы, которые начинаются с send_ формируют события в боте (отправляют сообщения, генерируют кнопки и т.д.).
3. Методы не имеющие указанные "префиксы" позволяют удалять, изменять сообщения, либо являются вспомогательными.
4. В основном цикле Вашей программы осуществляем запрос происходящих с ботом событий методом get_updates. Результат помещаем в переменную, например upd = get_updates().
5. Результат работы сформированных вами событий так же можно поместить в переменную, например res = send_message(text, chat_id). Чаще всего из результата сформированного события требуется получить параметр message_id с помощью которого в дальнейшем можно изменять (удалять) данное событие (сообщение, контент).
6. Для получения "тела" события, которое необходимо обработать, передаем переменную upd выбранному методу get_ , например get_text(upd), работаем с результатом. Если запрошенное событие не произошло в ответ получим None.
7. Предлагаемая конструкция кода:

from botapitamtam import BotHandler

bot = BotHandler('access_token_primebot')

def main():
    while True:
        upd = bot.get_updates()  # получаем внутреннее представление сообщения (контента) отправленного боту (сформированного ботом)
        # тут можно вставить любые действия которые должны выполняться во время ожидания события
        if upd: # основной код, для примера представлен эхо-бот
            chat_id = bot.get_chat_id(upd)
            text = bot.get_text(upd)
            bot.send_message(text, chat_id)

if __name__ == '__main__':
    try:
        main()
    except KeyboardInterrupt:
        exit()

8. Для работы с библиотекой поместите файл botapitamtam.py в каталог с вашим кодом. Для удобного использования библиотеки во многих ботах с возможностью получения обновлений необходимо клонировать репозиторий в отдельный каталог (git clone https://github.com/registriren/botapitamtam), а символьную ссылку на файл botapitamtam.py разместить в каталогах с вашими ботами.
9. Отправка простого однотипного контента (текст и фото, текст и видео, текст и кнопки) в чат осуществляется с помощью методов send_image, send_video, send_buttons.
10. Формирование кнопок осуществляется в несколько этапов:

• Готовим кнопки в зависимости от типа (callback, link, request_contact, request_geo_location, chat) с помощью соответствующих методов button_callback, button_link, button_contact и т.п. результат работы методов присваем переменной, например key1 = button_callback('Кнопка1', 'payload-key1')
• Если необходимо объединить кнопки в строку key_str = [[key1, key2, key3]]
• Если необходимо объединить кнопки в столбец key_stb = [[key4], [key5]]
• Можно сочетать вышеуказанные правила или просто сложить подготавливаемые кнопки key_res = key_str + key_stb
• Теперь можно отправить кнопки в бот методом send_buttons(text, key_res, chat_id) или сделать их частью attachments для совместной отправки с другим контентом (фото, видео и т.п.) при помощи соответствующих методов (send_message, send_answer_callback, edit_message и др.), содержащих в качестве параметра attachments=
• Примеры в разделе Examples

Описание методов (также смотрите в основном коде):

Получение информации о событиях в чате с ботом

• get_updates - получение событий, произошедших в чате с ботом (боту отправлено текстовое сообщение, картинка, видео, нажата кнопка и т.д.) С результатом работы, помещенным в переменную (например update) этого метода, работают нижеперечисленные методы:
  • get_marker - получает маркер (порядковый номер) следующего события, необходим в технических целях.
  • get_chat_id - получает идентификатор чата в которм происходит взаимодействие с ботом, только этот идентификатор требуется в следующих методах:
    • get_chat - получает информацию о текущем чате.
    • get_chat_admins - получает информацию об администраторах чата.
    • get_chat_membership - получает информацию о членстве в чате для текущего бота.
  • get_user_id - получает идентификатор пользователя полученного сообщения.
  • get_callback_id - получает значение callback_id (идентификатора клавиатуры), предназначенного для создания реакции на факт нажатия кнопки с помощью метода send_answer_callback.
  • get_payload - получает payload (текстовое значение, не путать с наименованием кнопки) нажатой кнопки.
  • get_text - получает значение поля text полученного сообщения (события).
  • get_message_id - получает идентификатор сообщения (события).
  • get_messages - возвращает список сообщений чата.
  • get_name - получает имя пользователя, сформировавшего событие.
  • get_username - получает username пользователя, сформировавшего событие.
  • get_is_bot - позволяет отличить пользователя от бота.
  • get_update_type - получает тип события (например bot_started), произошедшего с ботом.
  • get_attachments - получает весь прикрепленный к сообщению контент в различном сочетании (например несколько фото, видео).
  • get_url - получает значение поля URL полученного сообщения (события).
  • get_link_name - получает имя пользователя пересланного сообщения.
  • get_link_username - получает username пользователя пересланного сообщения.
  • get_link_user_id - получает идентификатор пользователя пересланного сообщения.
  • get_link_chat_id - получает идентификатор чата пересланного сообщения.
  • get_chat_type - получает значение поля chat_type (диалог, чат, канал).
  • get_attach_type - получает тип вложения (file, contact, share и т.п.) к сообщению отправленному или пересланному боту
• get_members - получает информацию о пользователях участвующих в чате.
• get_all_chats - получает информацию о чатах, в которых участвовал бот.
• get_bot_info - получает информацию о текущем боте.
  • get_bot_user_id - возвращает идентификатор текущего бота.
  • get_bot_name - возращает имя текущего бота.
  • get_bot_username - возвращает username текущего бота.
  • get_bot_avatar_url - возвращает ссылку на аватар текущего бота.
  • get_bot_full_avatar_url - возвращает ссылку на аватар большого размера текущего бота.
  • get_bot_commands - возвращает список команд текущего бота.
  • get_bot_description - возвращает описание текущего бота.
• get_subscriptions - возвращает список подписок на WebHook.
• add_members - добавляет пользователя в чат.

Подготовка контента (фото, видео, файл, кнопки) к совместной отправке в чат через параметр attachments=

• attach_audio - готовит аудио к совместной отправке с другим контентом.
• attach_file - готовит файл к совместной отправке с другим контентом.
• attach_image - готовит изображения к совместной отправке с другим контентом.
• attach_image_url - готовит изображения (по их URL) к совместной отправке с другим контентом.
• attach_video - готовит видео к совместной отправке с другим контентом.
• attach_buttons - готовит массив кнопок к совместной отправке с другим контентом, при этом сами кнопки предварительно формируются следующими методами:
  • button_callback - готовит кнопку с реакцией callback для дальнейшего формирования в массив.
  • button_contact - готовит кнопку запроса контакта пользователя для дальнейшего формирования в массив.
  • button_link - готовит кнопку со ссылкой на URL для дальнейшего формирования в массив.
  • button_location - готовит кнопку запроса местоположения для дальнейшего формирования в массив.
  • button_chat - готовит кнопку для создания нового чата, например чата для обсуждения.

Формирование (отправка, изменение) событий в чатах с ботом

• delete_message - удаляет сообщение (контент) по его идентификатору (message_id).
• edit_message - изм