Inline Keyboard Markup

Inline Keyboard Markup (встроенная клавиатурная разметка) — это формат данных в API мессенджеров (прежде всего Telegram), используемый для создания интерактивных кнопок, прикреплённых к сообщениям. В отличие от обычной клавиатуры, которая заменяет поле ввода и отправляет текст, inline-кнопки остаются в чате и позволяют пользователю взаимодействовать с ботом без отправки текстовых сообщений, путём отправки callback-данных (обратного вызова) или выполнения предопределённых действий (открытие URL, отправка команды, переход по инлайн-запросу). Данная разметка является основой для построения графических интерфейсов в текстовых чатах, таких как меню, опросы, каталоги и игры.

История

Появление в Telegram

Inline Keyboard Markup была впервые представлена в Telegram Bot API в апреле 2016 года, в версии API 2.0. До этого боты могли отправлять только обычные клавиатуры (ReplyKeyboardMarkup), которые после нажатия отправляли текст в чат. Внедрение inline-кнопок кардинально изменило функциональность ботов, позволив им создавать сложные, многоуровневые интерфейсы без необходимости вводить команды вручную. Первоначально поддерживались только кнопки с callback-данными и URL. Позднее, в версии 3.0 (2017 год), были добавлены кнопки для перехода по инлайн-запросам (switch_inline_query) и для отправки игр (callback_game).

Развитие и стандартизация

С момента появления формат inline-клавиатур стал де-факто стандартом для взаимодействия с ботами в Telegram. В 2018 году, с выходом API 4.0, была добавлена возможность создавать многострочные клавиатуры с разным количеством кнопок в строке, что позволило реализовывать более сложные макеты, например, таблицы и сетки. В 2020 году, с версией 5.0, появилась поддержка кнопок с запросом контакта или геолокации (KeyboardButtonRequestContact и KeyboardButtonRequestLocation), но только для обычных клавиатур; для inline-кнопок такие функции не были реализованы. На сегодняшний день формат inline-клавиатур остаётся стабильным и не претерпел кардинальных изменений, хотя периодически добавляются новые типы кнопок (например, кнопки для создания чатов или для оплаты через Telegram Stars).

Структура и формат

Базовые элементы

Inline Keyboard Markup представляет собой JSON-объект, который передаётся в параметре reply_markup при отправке сообщения. Основной элемент — массив inline_keyboard, который содержит массивы кнопок (строки). Каждая кнопка — это объект с обязательным полем text (текст на кнопке) и одним из полей действия:

• callback_data — строка (до 64 байт), которая отправляется боту при нажатии. Используется для обработки действий без перехода на внешние ресурсы.
• url — URL-адрес, который открывается при нажатии (обычно внешний сайт, но может быть и deep link, например, tg://resolve?domain=username).
• switch_inline_query — текст, который вставляется в поле ввода инлайн-режима при нажатии. Позволяет пользователю начать инлайн-запрос с этим текстом.
• switch_inline_query_current_chat — то же, но запрос выполняется в текущем чате.
• callback_game — используется для запуска игр (требуется предварительная настройка игры через BotFather).
• login_url — кнопка для авторизации через Telegram Login Widget.
• pay — кнопка для оплаты через Telegram Stars (требуется настройка платежей).

Пример разметки

``json { "inline_keyboard": [ [ {"text": "Кнопка 1", "callback_data": "action1"}, {"text": "Кнопка 2", "url": "https://example.com"} ], [ {"text": "Поиск", "switch_inline_query_current_chat": "запрос"} ] ] } ``

В этом примере первая строка содержит две кнопки: одна отправляет callback-данные action1, другая открывает сайт. Вторая строка — одна кнопка, которая запускает инлайн-запрос с текстом «запрос» в текущем чате.

Ограничения

• Максимальное количество кнопок в одной клавиатуре — 100 (по состоянию на 2024 год).
• Максимальное количество строк — 10 (но может быть меньше, если кнопок много).
• Текст каждой кнопки не должен превышать 64 символа (для большинства типов).
• Callback-данные не должны превышать 64 байта (в кодировке UTF-8). Это ограничение критично для сложных интерфейсов, где требуется передавать много данных.

Типы кнопок и их применение

Кнопки с callback-данными

Самый распространённый тип. При нажатии бот получает объект CallbackQuery, содержащий data (callback-данные), message (сообщение, к которому прикреплена клавиатура) и from (пользователь). Бот может обработать запрос, например, изменить текст сообщения, отредактировать клавиатуру или выполнить другое действие. Используются для:

• Меню (например, «Далее», «Назад», «Выбрать категорию»).
• Опросов (кнопки «Да», «Нет», «Воздержаться»).
• Пагинации (кнопки «Следующая страница», «Предыдущая страница»).

Кнопки с URL

Открывают внешний сайт или deep link в браузере Telegram. Используются для:

• Ссылок на статьи, товары, профили.
• Перехода на внешние сервисы (например, оплата через сторонний платёжный шлюз).
• Авторизации через Telegram Login Widget (кнопка login_url).

Кнопки с инлайн-запросами

Позволяют пользователю быстро начать инлайн-запрос с заданным текстом. Используются для:

• Поиска по каталогу (например, «Найти товары по запросу»).
• Запуска игр или приложений в инлайн-режиме.
• Быстрого доступа к функциям бота (например, «Поделиться этим сообщением»).

Кнопки для игр и платежей

• callback_game — для запуска игр, зарегистрированных в BotFather. При нажатии отправляется игровой запрос, и бот может запустить игру.
• pay — для оплаты через Telegram Stars. Требуется предварительная настройка платежей через BotFather и наличие у пользователя достаточного количества Stars.

Применение

В ботах Telegram

Inline-клавиатуры являются основным инструментом для создания пользовательских интерфейсов в ботах. Они используются в:

• Интернет-магазинах: кнопки «Купить», «Добавить в корзину», «Посмотреть описание», пагинация по товарам.
• Новостных агрегаторах: кнопки «Читать далее», «Перейти к источнику», «Поделиться».
• Играх: кнопки для управления персонажем, выбора действий, просмотра статистики.
• Образовательных ботах: кнопки для выбора темы, ответа на вопрос, перехода к следующему уроку.
• Сервисах заказа: кнопки «Заказать», «Отменить», «Выбрать дату», «Подтвердить».

В других мессенджерах

Хотя формат inline-клавиатур изначально разработан для Telegram, аналогичные концепции существуют и в других платформах:

• Discord: кнопки (Components) реализованы через MessageComponents с типом Button, поддерживают callback-данные и URL.
• VK: кнопки-действия (Callback) в сообщениях сообществ, но с ограниченной функциональностью (только callback-данные, без URL).
• **WhatsApp (продукт Meta, признанной экстремистской и запрещённой в РФ) Business API**: кнопки в интерактивных сообщениях (Interactive Message), но с жёсткими ограничениями (до 3 кнопок, только текст или URL).

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

Ограничения по размеру данных

Основная критика inline-клавиатур связана с ограничением на callback-данные (64 байта). Для сложных интерфейсов, где требуется передавать идентификаторы объектов, параметры фильтрации или сериализованные данные, этого часто недостаточно. Разработчики вынуждены использовать хитрости: хранить данные в сессии бота и передавать только короткий идентификатор, либо использовать базы данных для хранения состояния.

Отсутствие поддержки мультимедиа

Inline-кнопки не могут содержать изображения, анимации или другие медиафайлы. Текст кнопки — это всегда обычный текст (без форматирования). Это ограничивает возможности визуального оформления, особенно в сравнении с веб-интерфейсами.

Сложность отладки

Ошибки в разметке (например, неверный JSON, превышение лимита кнопок) приводят к тому, что клавиатура не отображается, а бот не получает никакого уведомления об ошибке. Разработчикам приходится тщательно проверять формат и тестировать на реальных пользователях.

Отсутствие поддержки в некоторых клиентах

Хотя Telegram поддерживает inline-клавиатуры во всех официальных клиентах, сторонние клиенты (например, Telegram X, Plus Messenger) могут отображать их некорректно или не поддерживать некоторые типы кнопок (например, login_url).

Интересные факты

• Использование в играх: Кнопки с callback_game позволяют запускать игры без необходимости вводить команду /game. Это сделало Telegram популярной платформой для простых браузерных игр (например, «2048», «Змейка»).
• Динамические клавиатуры: Боты могут редактировать клавиатуру в реальном времени, заменяя её на новую при каждом нажатии. Это позволяет создавать многоуровневые меню, где каждая кнопка меняет содержимое сообщения.
• Кнопки с авторизацией: login_url используется для создания кнопок «Войти через Telegram», что упрощает аутентификацию на сторонних сайтах.
• Влияние на UX: Исследования показывают, что использование inline-кнопок снижает количество ошибок ввода и повышает скорость взаимодействия с ботом на 30–40% по сравнению с текстовыми командами.

Источники

• Telegram Bot API Documentation (раздел «InlineKeyboardMarkup»)
• Telegram API Changelog (версии 2.0, 3.0, 4.0, 5.0)
• Статья «Building Interactive Bots with Inline Keyboards» на Habr (2021)
• Документация Discord API (раздел «Message Components»)
• Документация VK API (раздел «Кнопки в сообщениях»)
• Документация WhatsApp Business API (раздел «Interactive Messages»)