Bot API v2: Кнопки и редактирование сообщений
В начале апреля 2016 года вышло первое по-настоящему крупное обновление API для ботов. Изменений довольно много, поэтому материал я разобью на несколько частей. Сегодня поговорим об inline-кнопках и редактировании сообщений, а затем обсудим новые инлайн-режимы вместе со специальными кнопками для отправки геолокации и номера телефона.
Новые возможности
Начнём с двух важных изменений:
- Каждая кнопка, будь то обычная или инлайн, это теперь самостоятельный объект KeyboardButton или InlineKeyboardButton , не забудьте обновить своих ботов!
- В Inline-режиме все текстовые поля теперь представлены отдельными объектами InputMessageContent , которые, в свою очередь могут быть аж 4-х типов (подробности тут).
URL-кнопки
Итак, инлайн-кнопки. Что это такое? Это специальные объекты, которые “цепляются” к конкретным сообщениям и распространяют своё действие, в общем случае, только на них. Делятся такие кнопки на три типа: URL-кнопки, Callback-кнопки и Switch-кнопки. Самыми простыми являются кнопки-ссылки (URL). Как видно из названия, их цель — просто перекидывать пользователей по определенным веб-адресам. Давайте сразу напишем обработчик, который будет на любое сообщение отвечать каким-либо текстом и предложением перейти, например, на Яндекс.
Инлайн-клавиатура представляет собой объект InlineKeyboardMarkup , а каждая инлайн-кнопка – это объект InlineKeyboardButton . Чтобы получилась URL-кнопка, нужно указать значения параметров text (текст на кнопке) и url (валидный веб-адрес). В результате бот пришлет нам такое сообщение (см. рис.). В целях обеспечения безопасности, перед переходом по URL-кнопкам появляется всплывающее окно, в котором видна ссылка целиком.
Callback-кнопки и редактирование сообщений
Прежде, чем мы перейдем к другим кнопкам, давайте познакомимся с функциями редактирования сообщений, коих тоже три: editMessageText (редактирование текста), editMessageCaption (редактирование подписи к медиа) и editMessageReplyMarkup (редактирование инлайн-клавиатуры). В рамках этого урока рассмотрим только первую функцию, остальные работают аналогично и предлагаются для самостоятельного изучения.
Чтобы отредактировать сообщение, нам надо знать, про какое именно идёт речь. В случае, если оно было отправлено самим ботом, идентификаторами служит связка chat_id + message_id . Но если сообщение было отправлено в инлайн-режиме, то ориентироваться надо по параметру inline_message_id .
И вот теперь вернемся к нашим баранам кнопкам. На очереди – Callback. Это, на мой взгляд, самая крутая фича нового обновления. Колбэк-кнопки позволяют выполнять произвольные действия по их нажатию. Всё зависит от того, какие параметры каждая кнопка в себе несёт. Соответственно, все нажатия будут приводить к отправке боту объекта CallbackQuery , содержащему поле data , в котором написана некоторая строка, заложенная в кнопку, а также либо объект Message , если сообщение отправлено ботом в обычном режиме, либо поле inline_message_id , если сообщение отправлено в инлайн-режиме.
Приведу пример, после которого все вопросы должны отпасть: пусть, например, если сообщение отправлено ботом в обычном режиме, то нажатие на кнопку заменит текст сообщения на “Пыщь”, если в инлайн – то “Бдыщь”. При этом в обоих случаях значение callback_data будет равно test . Что для этого нужно сделать: во-первых, написать простейший хэндлер для всех входящих сообщений, во-вторых, написать простейший хэндлер для инлайн-сообщений, в-третьих, написать простейший хэндлер для колбэка, который определит, из какого режима пришло сообщение.
Запускаем бота, отправляем инлайн-сообщение, которое, в свою очередь, вызовет обычное:
Нажмем на обе кнопки, результат правильный:
После проверки
Таким образом, callback-кнопки – это очень мощный инструмент для взаимодействия пользователей с ботом, а редактирование сообщений дополнительно помогает в этом. Более того, нажатие на колбэк-кнопку может дополнительно тригернуть либо уведомление в верхней части экрана, либо всплывающее окно. Покажу первый вариант. Пускай помимо изменения сообщения на “Пыщь”, аналогичное слово показывается уведомлением. Для этого перепишем первое if-условие в хендлере колбэков:
Результат – на скриншоте. Попробуйте, кстати, изменить аргумент show_alert на True и посмотрите, что получится.
Всплывающее уведомление
Switch-кнопки
Наконец, остался последний тип кнопок — Switch (переключатель). Они нужны, чаще всего, для обучения пользователей работе с ботом в инлайн-режиме. Чтобы активировать сделать кнопку такого типа, нужно указать аргумент switch_inline_query либо пустой, либо с каким-либо текстом. В последнем случае этот текст будет сразу подставлен в поле ввода, например, для показа демонстрации инлайна. Как вообще работает такая кнопка? При нажатии на неё Telegram предложит выбрать чат, после чего подставит в поле ввода ник вашего бота и (если есть), текст, указанный вами в аргументе switch_inline_query . Давайте попробуем так сделать. Добавим кнопку, которая будет перенаправлять пользователя в какой-либо чат и предлагать в инлайн-режиме запрос “Telegram”. Код всего хендлера выглядит вот так:
Теперь, если мы нажмем на кнопку и выберем чат, вот что получится:
Итак, в этом уроке мы познакомились с новыми кнопками в Telegram Bot API, научились переписывать историю редактировать сообщения и отправлять небольшие уведомления по нажатию. В следующий раз продолжим изучать новые возможности для ботов. А исходники к этому уроку можно найти в этом репозитории.
Buttons
Users can interact with your bot via buttons or even inline buttons, straight from inline messages in any chat.
This article describes the full button flow, using the MTProto API.
For a simplified description using the HTTP bot API, see here ».
Buttons
Bots can attach a ReplyMarkup constructor to outgoing messages, to attach an inline keyboard or a custom reply keyboard:
-
— Sends a custom reply keyboard.
User clients receiving such a constructor should display a special keyboard with custom reply options. — Hides the custom reply keyboard.
User clients receiving this constructor should hide the custom reply keyboard opened by replyKeyboardMarkup — Sends a force reply constructor
User clients receiving a message with this constructor should act as if the user had clicked on the reply button of the message, displaying the reply UI. — Attaches an inline keyboard to the message, allowing users to send callback data to the bot without sending actual messages to the current chat.
Pressing buttons
Both reply and inline keyboards are composed of a vector of rows, each row containing a vector of buttons, for each column.
Each row can have a different number of columns, and user clients should properly handle clicking buttons of every type.
Buttons available only in reply keyboards:
-
— Send a message to the chat, replying to the message that attached the reply keyboard — Only in private chats, send the current user’s contact to the chat, replying to the message that attached the reply keyboard — Only in private chats, send the current user’s geolocation to the chat, replying to the message that attached the reply keyboard — Only in private chats, prompt the user to create and send a poll (or a quiz poll, depending on the quiz flag), replying to the message that attached the reply keyboard
Buttons available only in inline keyboards:
-
— Open the URL, showing a «Do you want to open this URL?» prompt (unless the URL is one of the internal URIs, in which case the URL should be opened right away) — Send the callback data to the bot, optionally providing the user’s 2FA SRP payload for identity verification, see here for more info »
- If keyboardButtonSwitchInline.same_peer is set, insert the bot’s username and keyboardButtonSwitchInline.query in the current chat’s input field, triggering an inline query.
- If keyboardButtonSwitchInline.same_peer is not set, prompt the user to select one of their chats, and then insert the bot’s username and keyboardButtonSwitchInline.query in the current chat’s input field, triggering an inline query.
- message if specified, a message that should be shown in a non-blocking toast notification
- alert indicates whether the message should be shown as a dismissible prompt, instead of a simple toast notification
- has_url Whether an URL is present
- url if specified, the client should open the URL, without showing a confirmation prompt.
This is safe and allowed, because here bots can only return: , if the bot has manually configured games, and the clicked button was a keyboardButtonGame.
Callback queries
keyboardButtonCallback buttons can be used to send the specified data payload back to the bot, when they are clicked.
Additionally, a bot can verify a user’s identity by requiring they verify their 2FA password with SRP.
Sending a callback query
When the user clicks on a keyboardButtonCallback in a message sent by a bot, or generated by an inline query, messages.getBotCallbackAnswer should be called, passing the peer and ID of the message.
The same should happen when clicking on keyboardButtonGame buttons, with the difference that the game flag must be set instead of the data parameter.
Make sure to properly handle bot timeouts in the form of BOT_RESPONSE_TIMEOUT RPC errors, as the bot may be offline and unable to reply.
The returned messages.botCallbackAnswer constructor contains:
SRP verification
If the requires_password flag is set, the SRP 2FA payload must also be generated and attached to the query, to verify the identity of the user.
Note that the bot will NOT be able to access your password or the SRP payload.
The SRP payload will be processed exclusively on the Telegram’s servers, simply returning an RPC error without passing the query to the bot if the verification fails.
This is just a way of verifying the identity of the user, mainly used by the official @botfather bot to allow securely transferring the ownership of a bot to another user.
Встроенные кнопки в 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к пользователей ежедневно. Именно поэтому важно подхватить тренд и разобраться с его основными особенностями, т.к. различные методы взаимодействия с ботами существенно облегчает жизнь разработчиков и пользователей.
Кнопки в телеграм-ботах
Это статья из серии о телеграм-ботах. Я по частям расскажу о важных моментах в pytelegrambotapi. Сразу полезная информация: я начал учиться делать ботов по этой статье и всем ее рекомендую.
Кнопки в телеграм бывают двух видов — inline и обычные (reply).
Обычные вы видите вместо клавиатуры, все, что они делают, как правило, — отправляют текстовое сообщение боту.
Но, перед тем, как сделать кнопку, нужно создать клавиатуру. Для обычных кнопок она одна, для inline другая, вот обычная:
resize_keyboard: bool — необязательный | будет ли клавиатура растягиваться (по умолчанию: без значения)
one_time_keyboard: bool — необязательный \ разовая ли клавиатура (по умолчанию: без значения)
selective: bool — необязательный | кому показывать (по умолчанию: без значения)
row_width: int — обязательный | количество столбцов кнопок (по умолчанию: 3)
input_field_placeholder: str — необязательный | заменяет текст-заглушку в поле ввода (по умолчанию: без значения)
Создав клавиатуру, создадим к ней кнопку:
text: str — обязательный | текст кнопки. Если указан только он, то кнопка будет просто отправлять текст при нажатии.
request_contact: bool — необязательный | если указан как true то пользователь при нажатии отправит свой контакт. Доступен только в приватных чатах.
request_location: bool — необязательный | если указан как true, то пользователь при нажатии отправит свою локацию. Доступен только в приватных чатах.
request_poll: bool — необязательный | если указан как true, то пользователь при нажатии отправит свою локацию. Доступен только в приватных чатах.
web_app: WebAppInfo — необязательный | если указан как true, то при нажатии откроется страница указанного веб-приложения — про это есть отдельная статья. Доступен только в приватных чатах.