Встроенные кнопки в Telegram Bot API — pyTelegramBotAPI
Добрый день уважаемые читатели, давайте рассмотрим, какие основные типы встроенных кнопок предлагают чат-боты telegram и в чем их особенности. Статья будет полезна всем, кто хочет разобраться в возможностях взаимодействия с пользователями telegram в версии bot API 2.0.
Для обзора возможностей нам понадобится установить 3 целых 2 десятых Python`a и пару ложек pyTelegramBotAPI. Особенности настройки и регистрации чат-бота мы рассматривать не будем, т.к. есть множество статей на эту тему.
И так, что же такое встроенные кнопки(клавиатура) в мессенджере Telegram? Это кнопки которые выводятся во внутренней области чата и привязываются к конкретному сообщению. Они жестко связаны с сообщением(если удалить сообщение, внутренние кнопки так же удаляются вместе с ним.). Они дают возможность динамически видоизменять его.
В данный момент есть три типа встроенных кнопок:
URL-кнопки
Для создания кнопки используется тип InlineKeyboardMarkup, давайте создадим кнопку «Наш сайт»:
Тут название говорит само за себя, это тип кнопок предназначен для перенаправления пользователя по ссылке, с соответствующим предупреждением. Кнопка имеет соответствующий ярлычок в правом верхнем углу, чтобы дать понять пользователю, что это ссылка.
Switch-кнопки
Этот тип кнопок предназначен для перенаправления пользователя в какой либо чат, с последующей активацией (встроенного) inline-режима общения с ботом. Данный режим можно активировать вручную: в чате, вводим: «@название бота», но switch-кнопки позволяют это сделать автоматически (помогая знакомиться с inline-режимом новичкам).
Для того что-бы создать подобный переключатель, необходимо указать аргумент switch_inline_query либо пустой, либо с каким-либо текстом.
Теперь, если мы нажмем на кнопку и выберем чат, вот что получится:
Шаг 1: 
Нажимаем на кнопку.
Шаг 2: 
Выбираем чат.
Шаг 3: 
Активировался встроенный inline-режим.
Callback-кнопки
Ну и наконец самое интересное — это кнопки с обратной связью: позволяют динамически обновлять сообщение/встроенные кнопки (не засоряя при этом ленту), а так же отображать уведомление в верху чат-бота или модальном окне.
Например, их можно использовать для просмотра длинного сообщения, аналогично пагинации страниц на сайтах, или например сделать календарь. Я не стану изобретать велосипед, а через поиск по GitHub, найду готовую библиотеку calendar-telegram. Выполнив указанные инструкции, получаем готовый календарь, который можно динамически изменять по нажатию на соответствующие кнопки: 
Так же можно добавить уведомление по нажатию на дату, для этого достаточно указать сообщение в ответе:
(Пример в десктопной версии)
(Пример в мобильной версии)
Если изменить show_alert на True, то мы получим модальное окно:
Заключение
По последним данным, в нашумевшем мессенджере Telegram регистрируются больше 600к пользователей ежедневно. Именно поэтому важно подхватить тренд и разобраться с его основными особенностями, т.к. различные методы взаимодействия с ботами существенно облегчает жизнь разработчиков и пользователей.
Меню из кнопок, модуль python-telegram-bot в Python.
Создание на Telegram меню из кнопок (встроенные клавиатуры).
Всякий раз, когда бот отправляет сообщение, он может передать специальную клавиатуру с предопределенными параметрами ответа. Приложения Telegram, которые получают сообщение, будут отображать эту клавиатуру для пользователя. Нажатие любой из кнопок немедленно отправит соответствующую команду. Таким образом можно значительно упростить взаимодействие пользователя с ботом.
Содержание.
Встроенные клавиатуры Telegramm в сообщения бота.
Бывают случаи, когда нужно что-либо сделать, не отправляя никаких сообщений в чат. Например, когда пользователь меняет настройки или просматривает результаты поиска. В таких случаях можно использовать встроенные InlineKeyboardButton клавиатуры, которые интегрированы непосредственно в сообщения, которым они принадлежат.
В отличие от настраиваемых клавиатур KeyboardButtons , которые посылают текст кнопки в качестве ответа, нажатие кнопок на встроенных клавиатурах InlineKeyboardButton не приводит к отправке сообщений в чат. Вместо этого встроенные клавиатуры поддерживают кнопки, которые работают за кулисами: кнопки обратного вызова, кнопки с URL и переключение на встроенные кнопки.
Когда используются кнопки обратного вызова (с аргументом callback_data ), бот может обновлять свои существующие сообщения или клавиатуры. При нажатии на такую кнопку, бот просто получает соответствующий запрос. Получив запрос, бот может отображать результат в уведомлении в верхней части экрана чата или в предупреждении.
Классы KeyboardButton и InlineKeyboardButton .
Данные классы определяют атрибуты и методы, одноименные с названиями аргументов.
KeyboardButton(text, request_contact=None, request_location=None, request_poll=None, **_kwargs) :
Объект KeyboardButton представляет собой одну кнопку клавиатуры для ответа текстом text , который отображается на кнопке. Необязательные аргументы исключают друг друга. Импортируется из основного модуля telegram.KeyboardButton .
Значение и поведение аргументов KeyboardButton :
- text (str) — текст кнопки. Если ни одно из дополнительных полей не используется, оно будет отправлено боту в виде сообщения при нажатии кнопки.
- request_contact (bool, необязательно) — если True , то при нажатии будет отправлен телефонный номер пользователя, как контакт. Доступно только в приватных чатах.
- request_location (bool, необязательный) — если True , то при нажатии будет отправлено текущее местоположение пользователя. Доступно только в приватных чатах.
- request_poll (KeyboardButtonPollType, необязательно) — если указано, то при нажатии кнопки пользователю будет предложено создать опрос и отправить его боту. Доступно только в приватных чатах.
- **_kwargs (dict) — произвольные ключевые аргументы.
InlineKeyboardButton(text, url=None, callback_data=None, switch_inline_query=None, switch_inline_query_current_chat=None, callback_game=None, pay=None, login_url=None, **_kwargs)
Объект InlineKeyboardButton представляет одну кнопку встроенной клавиатуры. Допускается использовать ровно одно из необязательных полей. Импортируется из основного модуля telegram.InlineKeyboardButton .
Значение и поведение аргументов InlineKeyboardButton :
- text (str) — текст кнопки. Если ни одно из дополнительных полей не используется, оно будет отправлено боту в виде сообщения при нажатии кнопки.
- url (str) — HTTP или tg://url, который открывается при нажатии кнопки.
- login_url (telegram.LoginUrl, необязательно) — URL-адрес HTTP, используемый для автоматической авторизации пользователя. Может использоваться как замена виджета входа в Telegram.
- callback_data (str, необязательно) — данные, которые будут отправлены в запросе обратного вызова боту при нажатии кнопки, UTF-8 1-64 байта.
- switch_inline_query (str, необязательно) — если установлено, то нажатие кнопки предложит пользователю выбрать один из своих чатов, открыть этот чат и вставить логин бота и указанный встроенный запрос в поле ввода. Может быть пустым, и в этом случае будет вставлено только логин бота. Это дает пользователям простой способ начать использовать вашего бота во встроенном режиме, в то время как они находятся с ним в приватном чате. Особенно полезно в сочетании с действиями switch_pm* — в этом случае пользователь автоматически вернется в чат, из которого он переключился, пропуская экран выбора чата.
- switch_inline_query_current_chat (str, необязательно) — если установлено, то нажатие кнопки вставит логин бота и указанный встроенный запрос в поле ввода текущего чата. Может быть пустым, и в этом случае будет вставлено только логин бота. Это предлагает пользователю быстрый способ открыть вашего бота во встроенном режиме в том же чате — удобно для выбора чего-либо из нескольких вариантов.
- callback_game (telegram.CallbackGame, необязательно) — описание игры, которая будет запускаться при нажатии кнопки пользователем. Кнопка этого типа всегда должна быть первой кнопкой в первом ряду.
- pay (bool, необязательно) — укажите True , чтобы отправить кнопку Pay. Кнопка этого типа всегда должна быть первой кнопкой в первом ряду.
- **_kwargs (dict) — произвольные ключевые аргументы.
Алгоритм построения и отправки кнопок в Telegram чат.
Для создания макета кнопок со столбцами n_cols из списка кнопок необходимо создать функцию build_menu() , которая будет шаблоном для построения кнопок:
В коде выше определены списки header_buttons и footer_buttons , их можно использовать чтобы поместить кнопки в первую или последнюю строку соответственно.
В приведенном ниже фрагменте кода нужно заменить . соответствующим значением аргумента callback_data — это строка (UTF-8 1-64 байта) с данными, отправляемые боту в ответном запросе при нажатии кнопки. Если будете использовать кнопки KeyboardButtons для создания списка кнопок button_list , то для построения передаваемой в чат клавиатуры из кнопок используйте ReplyKeyboardMarkup вместо InlineKeyboardMarkup .
Или, если нужна динамическая версия, используйте генератор списка для динамического создания button_list из списка строк:
Это особенно полезно, если поместить внутрь вспомогательного метода, такого как get_data_buttons , для работы с динамическими данными и обновления меню в соответствии с вводом пользователя.
Чтобы обработать callback_data , необходимо подключить обработчик CallbackQueryHandler .
Обработчик сообщений CallbackQueryHandler .
Обработчик сообщений CallbackQueryHandler определяет атрибуты и методы, одноименные с названиями аргументов. Обработчик CallbackQueryHandler импортируется из модуля расширения telegram.ext .
CallbackQueryHandler(callback, pattern=None, run_async=False) :
Объект CallbackQueryHandler представляет собой обработчик запросов обратного вызова Telegram. Может использовать дополнительную фильтрацию на основе регулярных выражений модуля re .
Значение и поведение аргументов InlineKeyboardButton :
- callback — Функция обратного вызова для этого обработчика. Будет вызываться, когда сообщение должно быть обработано этим обработчиком.
- pattern=None ( str , необязательно) — шаблон регулярного выражения. Если не None , то для поиска совпадений в telegram.CallbackQuery.data (должно ли сообщение обрабатываться этим обработчиком) будет использоваться функция re.match() .
- run_async=False ( bool ) — определяет, будет ли обратный вызов выполняться асинхронно.
Остальные аргументы устарели. Такие параметры, как update_queue , job_queue , groups , groupdict , user_data , chat_data функциях обратного вызова можно получить объект контекста context
Базовый пример, использующий встроенную клавиатуру.
Пример встроенной клавиатуры с 2-мя состояниями.
Данный пример снабжен комментариями, так что понять как и что работает не составит труда. Он так же демонстрирует использование обработчиков CallbackQueryHandler и ConversationHandler .
Как работает обработчик разговора ConversationHandler() .
Основная магия происходит в обработчике разговора ConversationHandler() . Обработчик ConversationHandler() имеет три основные точки, которые необходимо определить для ведения беседы:
- entry_points — точка входа в разговор, представляет собой список обработчиков, которые запускают разговор. Разговор можно запустить по команде, отправленной пользователем (в данном случае /start ) и/или по каким то фразам, которые можно поймать при помощи обработчика MessageHandler() и фильтра Filters.regex (например: Filters.regex('(поговорим|скучно)'), callback_func)],
- states — состояния разговора. Представляет собой словарь, в котором ключ, это этап разговора, который явно возвращает функция обратного вызова, при этом высылает или отвечает на сообщение или передает кнопки для выбора и т.д. Так вот, реакция/ответ пользователя на это сообщение/нажатие кнопки будет обрабатываться обработчиками, находящихся в списке значений этого ключа — этапа/состояния разговора.
- fallbacks — точка выхода из разговора. Разговор заканчивается, если функция обработчик сообщения явно возвращает return ConversationHandler.END
Переключение между этапами разговора происходит при помощи функций обратного вызова, которые при обработке/анализе ответа пользователя будут возвращать нужный этап/состояние разговора.
telegram.CallbackQuery¶
This object represents an incoming callback query from a callback button in an inline keyboard.
If the button that originated the query was attached to a message sent by the bot, the field message will be present. If the button was attached to a message sent via the bot (in inline mode), the field inline_message_id will be present.
Objects of this class are comparable in terms of equality. Two objects of this class are considered equal, if their id is equal.
In Python from is a reserved word, use from_user instead.
Exactly one of the fields data or game_short_name will be present.
After the user presses an inline button, Telegram clients will display a progress bar until you call answer . It is, therefore, necessary to react by calling telegram.Bot.answer_callback_query even if no notification to the user is needed (e.g., without specifying any of the optional parameters).
If you’re using Bot.arbitrary_callback_data , data may be an instance of telegram.ext.InvalidCallbackData . This will be the case, if the data associated with the button triggering the telegram.CallbackQuery was already deleted or if data was manipulated by a malicious client.
New in version 13.6.
id ( str ) – Unique identifier for this query.
from_user ( telegram.User ) – Sender.
chat_instance ( str ) – Global identifier, uniquely corresponding to the chat to which the message with the callback button was sent. Useful for high scores in games.
message ( telegram.Message , optional) – Message with the callback button that originated the query. Note that message content and message date will not be available if the message is too old.
data ( str , optional) – Data associated with the callback button. Be aware that a bad client can send arbitrary data in this field.
inline_message_id ( str , optional) – Identifier of the message sent via the bot in inline mode, that originated the query.
game_short_name ( str , optional) – Short name of a Game to be returned, serves as the unique identifier for the game
bot ( telegram.Bot , optional) – The Bot to use for instance methods.
Unique identifier for this query.
Global identifier, uniquely corresponding to the chat to which the message with the callback button was sent.
Optional. Message with the callback button that originated the query.
Optional. Data associated with the callback button.
Optional. Identifier of the message sent via the bot in inline mode, that originated the query.
Optional. Short name of a Game to be returned.
The Bot to use for instance methods.
MAX_ANSWER_TEXT_LENGTH : ClassVar [ int ] = 200 ¶
New in version 13.2.
For the documentation of the arguments, please see telegram.Bot.answer_callback_query() .
On success, True is returned.
copy_message ( chat_id , caption = None , parse_mode = None , caption_entities = None , disable_notification = None , reply_to_message_id = None , allow_sending_without_reply = None , reply_markup = None , timeout = None , api_kwargs = None , protect_content = None ) ¶
For the documentation of the arguments, please see telegram.Message.copy() .
On success, returns the MessageId of the sent message.
delete_message ( timeout = None , api_kwargs = None ) ¶
For the documentation of the arguments, please see telegram.Message.delete() .
On success, True is returned.
edit_message_caption ( caption = None , reply_markup = None , timeout = None , parse_mode = None , api_kwargs = None , caption_entities = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
edit_message_live_location ( latitude = None , longitude = None , location = None , reply_markup = None , timeout = None , api_kwargs = None , horizontal_accuracy = None , heading = None , proximity_alert_radius = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
edit_message_media ( media = None , reply_markup = None , timeout = None , api_kwargs = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
edit_message_reply_markup ( reply_markup = None , timeout = None , api_kwargs = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
edit_message_text ( text , parse_mode = None , disable_web_page_preview = None , reply_markup = None , timeout = None , api_kwargs = None , entities = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
get_game_high_scores ( user_id , timeout = None , api_kwargs = None ) ¶
Shortcut for either:
For the documentation of the arguments, please see telegram.Bot.get_game_high_scores() and telegram.Message.get_game_high_score() .
pin_message ( disable_notification = None , timeout = None , api_kwargs = None ) ¶
For the documentation of the arguments, please see telegram.Message.pin() .
On success, True is returned.
set_game_score ( user_id , score , force = None , disable_edit_message = None , timeout = None , api_kwargs = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
stop_message_live_location ( reply_markup = None , timeout = None , api_kwargs = None ) ¶
Shortcut for either:
On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.
unpin_message ( timeout = None , api_kwargs = None ) ¶