InlineKeyboardMarkup

InlineKeyboardMarkup — это структура данных в библиотеке Telegram Bot API, используемая для создания интерактивных кнопок, встроенных непосредственно в сообщение (инлайн-кнопок). Относится к классу объектов, описывающих разметку клавиатуры, и применяется для реализации пользовательских интерфейсов в ботах мессенджера Telegram. В отличие от ReplyKeyboardMarkup (обычной клавиатуры под полем ввода), InlineKeyboardMarkup прикрепляется к конкретному сообщению и не исчезает после нажатия, а также позволяет передавать боту callback-данные или открывать внешние ссылки.

История и контекст появления

Протокол Telegram Bot API был запущен в 2015 году. Изначально боты могли отвечать только текстовыми сообщениями и простыми командами. Внедрение инлайн-кнопок (InlineKeyboardMarkup) произошло в обновлении Bot API версии 2.0 (апрель 2016 года). Это нововведение значительно расширило функциональность ботов, позволив создавать многошаговые сценарии, меню, игры и формы без необходимости вводить текст вручную. С тех пор InlineKeyboardMarkup стал одним из основных инструментов для разработки интерактивных ботов в Telegram.

Структура и формат данных

InlineKeyboardMarkup представляет собой JSON-объект, содержащий единственное поле inline_keyboard. Это поле является массивом массивов объектов InlineKeyboardButton. Каждый внутренний массив соответствует одному ряду кнопок, отображаемых горизонтально. Внешний массив определяет количество рядов.

InlineKeyboardButton

Каждая кнопка описывается объектом со следующими ключевыми полями:

• text (строка, обязательное) — текст, отображаемый на кнопке.
• callback_data (строка, необязательное) — данные, которые будут отправлены боту при нажатии кнопки. Максимальная длина — 64 байта. Используется для обработки нажатий внутри бота.
• url (строка, необязательное) — URL-адрес, который откроется при нажатии кнопки. Не может быть использован одновременно с callback_data.
• login_url (объект, необязательное) — кнопка для авторизации пользователя через Telegram.
• switch_inline_query (строка, необязательное) — при нажатии открывает чат для выбора и вставляет указанный запрос в поле ввода.
• switch_inline_query_current_chat (строка, необязательное) — аналогично, но для текущего чата.
• callback_game (объект, необязательное) — кнопка для запуска игры.
• pay (логическое, необязательное) — кнопка для оплаты (используется в платежных системах Telegram).

Пример JSON

``json { "inline_keyboard": [ [ {"text": "Кнопка 1", "callback_data": "btn1"}, {"text": "Сайт", "url": "https://example.com"} ], [ {"text": "Кнопка 2", "callback_data": "btn2"} ] ] } ``

В этом примере создается клавиатура из двух рядов: первый ряд содержит две кнопки (одна с callback, другая с URL), второй ряд — одну кнопку.

Принцип работы

При отправке сообщения бот может включить в него объект reply_markup, содержащий InlineKeyboardMarkup. Telegram-клиент отображает кнопки под текстом сообщения. При нажатии на кнопку:

• Если указан callback_data, клиент отправляет боту объект CallbackQuery, содержащий идентификатор нажатия, данные кнопки и информацию о пользователе. Бот должен ответить на callback-запрос в течение 30 секунд (обычно отправляется пустой ответ или уведомление).
• Если указан url, клиент открывает ссылку во встроенном браузере или внешнем приложении. Бот не получает уведомления о таком нажатии.
• Если указан switch_inline_query, клиент переключается в режим выбора чата и вставляет запрос.

Классификация и виды использования

По типу действия

1. Callback-кнопки — передают данные боту, используются для навигации, выбора опций, подтверждения действий.
2. URL-кнопки — открывают внешние веб-страницы, часто применяются для ссылок на сайты, документы, каналы.
3. Кнопки авторизации — реализуют вход через Telegram (Login Widget).
4. Кнопки инлайн-запроса — позволяют пользователю быстро отправить запрос в другой чат.
5. Платежные кнопки — используются для проведения платежей через Telegram Stars или сторонние платежные системы.

По сценариям применения

• Меню и навигация — многоуровневые меню с callback-кнопками, где каждая кнопка меняет содержимое сообщения.
• Опросы и голосования — кнопки с вариантами ответов, подсчет голосов ведется на стороне бота.
• Игры — кнопки для управления игровым процессом (например, в играх на HTML5).
• Формы и заявки — пошаговый сбор данных с помощью кнопок «Да/Нет», выбора из списка.
• Интеграция с веб-сервисами — кнопки «Подписаться», «Открыть статью», «Перейти в магазин».

Особенности и ограничения

• Максимальное количество кнопок — не более 100 (в сумме по всем рядам). Количество рядов не ограничено, но на практике при большом числе кнопок интерфейс становится неудобным.
• Длина текста кнопки — не более 128 символов (рекомендуется короче для читаемости).
• Callback-данные — ограничены 64 байтами, что требует компактного кодирования (например, использование коротких идентификаторов или чисел).
• Одновременное использование — кнопки с callback_data и url могут быть в одном ряду, но одна кнопка не может иметь оба поля.
• Обновление сообщения — после нажатия callback-кнопки бот может отредактировать сообщение (изменить текст, клавиатуру), что позволяет создавать динамические интерфейсы без отправки новых сообщений.

Примеры реализации (на Python с библиотекой python-telegram-bot)

Отправка сообщения с инлайн-кнопками

```python from telegram import InlineKeyboardButton, InlineKeyboardMarkup

button1 = InlineKeyboardButton("Нажми меня", callback_data="press") button2 = InlineKeyboardButton("Сайт", url="https://example.com";) keyboard = [[button1, button2]] reply_markup = InlineKeyboardMarkup(keyboard)

await update.message.reply_text("Выберите действие:", reply_markup=reply_markup) ```

Обработка callback-запроса

``python async def button_callback(update, context): query = update.callback_query await query.answer() # обязательный ответ if query.data == "press": await query.edit_message_text(text="Вы нажали кнопку!") ``

Сравнение с ReplyKeyboardMarkup

Значение и применение

InlineKeyboardMarkup является ключевым элементом для создания удобных и функциональных ботов в Telegram. Он позволяет реализовать сложные сценарии без необходимости ввода текста пользователем, что особенно важно для мобильных устройств. Благодаря этой технологии стали возможны такие популярные боты, как боты для заказа еды, билетов, новостные агрегаторы, игровые боты и многие другие. InlineKeyboardMarkup также используется в каналах для создания интерактивных постов с кнопками «Подписаться», «Читать далее» и т.д.

Критика и ограничения

Основные недостатки InlineKeyboardMarkup связаны с ограничениями на размер callback-данных и отсутствием возможности вложенности (все кнопки одного уровня). Для создания сложных меню разработчикам приходится вручную управлять состояниями и перерисовывать клавиатуру. Кроме того, отсутствие визуальной обратной связи (например, анимации нажатия) может снижать пользовательский опыт. Некоторые разработчики отмечают, что при большом количестве кнопок интерфейс становится перегруженным.

Источники

• Официальная документация Telegram Bot API: раздел «InlineKeyboardMarkup» и «InlineKeyboardButton».
• Описание протокола Bot API версии 2.0 (апрель 2016 года).
• Документация библиотеки python-telegram-bot (версия 20.x).
• Статьи и руководства по разработке ботов на Telegram (Habr, Medium).