Открыть сервис
Главная → Блог → CallbackQuery

CallbackQuery

CallbackQuery — это объект в Telegram Bot API, представляющий собой запрос обратного вызова, который отправляется боту при нажатии пользователем на одну из встроенных кнопок (InlineKeyboardButton) в интерфейсе мессенджера Telegram. CallbackQuery является механизмом, позволяющим реализовать интерактивное взаимодействие с пользователем без необходимости отправлять текстовое сообщение в чат, инициируя выполнение определённых действий на стороне бота.

История

Механизм CallbackQuery был введён в Telegram Bot API в 2016 году, в рамках обновления, которое добавило поддержку встроенных клавиатур (InlineKeyboardMarkup). До этого момента взаимодействие с ботами ограничивалось текстовыми командами и кнопками под полем ввода (ReplyKeyboardMarkup), которые не позволяли передавать боту никаких дополнительных данных, кроме текста сообщения.

Внедрение CallbackQuery стало значительным шагом в развитии ботов Telegram, так как позволило создавать многоуровневые меню, формы, игры и другие интерактивные элементы, не требующие от пользователя ввода текста. Первоначально объект содержал только базовые поля: id, from, message, inline_message_id, chat_instance, data и game_short_name. Со временем API расширялся: были добавлены поля message_id для сообщений, не являющихся частью чата, и поле via_bot для указания бота, отправившего сообщение.

Структура объекта

CallbackQuery представляет собой JSON-объект, который Telegram отправляет на сервер бота при нажатии кнопки. Основные поля объекта:

  • id (строка) — уникальный идентификатор запроса, генерируемый сервером Telegram.
  • from (объект User) — пользователь, нажавший кнопку.
  • message (объект Message, опционально) — сообщение, к которому прикреплена клавиатура, если кнопка была встроена в сообщение чата.
  • inline_message_id (строка, опционально) — идентификатор сообщения, отправленного в режиме inline (без чата), если кнопка была встроена в такое сообщение.
  • chat_instance (строка) — уникальный идентификатор экземпляра чата, в котором было отправлено сообщение с кнопкой. Используется для защиты от атак повторного использования.
  • data (строка, опционально) — данные, связанные с кнопкой, которые бот задаёт при создании клавиатуры. Максимальная длина — 64 байта.
  • game_short_name (строка, опционально) — короткое имя игры, если кнопка была связана с игрой.

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

При нажатии пользователем на встроенную кнопку Telegram отправляет на сервер бота HTTP-запрос с объектом CallbackQuery. Бот должен обработать этот запрос и, как правило, ответить с помощью метода answerCallbackQuery, который уведомляет Telegram о том, что запрос принят. Без вызова этого метода Telegram будет повторно отправлять CallbackQuery в течение определённого времени (обычно 30 секунд).

Метод answerCallbackQuery может принимать следующие параметры:

  • callback_query_id (обязательный) — идентификатор запроса.
  • text (опционально) — текст всплывающего уведомления, которое увидит пользователь.
  • show_alert (опционально, булево) — если true, уведомление будет показано в виде модального окна, а не всплывающей подсказки.
  • url (опционально) — URL, который будет открыт в браузере пользователя (только для кнопок с типом url).
  • cache_time (опционально) — время в секундах, в течение которого результат будет кэшироваться на стороне клиента.

После обработки CallbackQuery бот может изменить содержимое сообщения, к которому прикреплена клавиатура, с помощью методов editMessageText, editMessageCaption, editMessageMedia или editMessageReplyMarkup. Это позволяет создавать динамические интерфейсы, например, перелистывание страниц списка или обновление состояния формы.

Применение

Многоуровневые меню

CallbackQuery широко используется для создания многоуровневых меню, где нажатие на кнопку приводит к изменению текста сообщения и замене клавиатуры на новую. Например, в боте для заказа пиццы пользователь может выбирать категорию (пиццы, напитки, десерты), а затем конкретный товар, при этом каждый шаг обрабатывается через CallbackQuery.

Формы и опросы

Боты могут собирать данные от пользователей через последовательность вопросов, где каждый ответ выбирается нажатием кнопки. CallbackQuery позволяет передавать кодированные данные (например, “question_1_answer_2”), которые бот расшифровывает и сохраняет.

Игры

В Telegram Gaming Platform CallbackQuery используется для обработки действий в играх, таких как выбор хода или ответ на вопрос. Поле game_short_name позволяет боту определить, какая игра была запущена.

Пагинация

При отображении больших списков (например, результатов поиска или каталога товаров) CallbackQuery позволяет реализовать постраничную навигацию. Кнопки «Вперёд» и «Назад» передают номер страницы в поле data, и бот обновляет сообщение, отображая соответствующий фрагмент.

Подтверждение действий

CallbackQuery может использоваться для кнопок подтверждения, например, «Подтвердить заказ» или «Отменить». После нажатия бот обрабатывает запрос и либо выполняет действие, либо показывает сообщение об ошибке.

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

  • Максимальная длина data — 64 байта, что ограничивает объём передаваемой информации. Для передачи более сложных данных боты часто используют кодирование (например, base64) или хранение состояния на своём сервере.
  • Время жизни запроса — CallbackQuery должен быть обработан в течение 30 секунд, иначе Telegram может повторно отправить его. Это важно для ботов с высокой нагрузкой.
  • Безопасность — поле chat_instance защищает от атак, когда злоумышленник пытается повторно использовать CallbackQuery в другом чате. Бот должен проверять это поле, если требуется строгая изоляция.
  • Ограничение на количество кнопок — Telegram позволяет добавлять до 8 кнопок в ряд и до 100 кнопок на одно сообщение, что влияет на проектирование интерфейсов.

Примеры использования

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

```python from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup from telegram.ext import Application, CommandHandler, CallbackQueryHandler

async def start(update: Update, context): keyboard = [[InlineKeyboardButton("Нажми меня", callback_data='button_pressed')]] reply_markup = InlineKeyboardMarkup(keyboard) await update.message.reply_text('Привет! Нажми кнопку:', reply_markup=reply_markup)

async def button_callback(update: Update, context): query = update.callback_query await query.answer() await query.edit_message_text(text="Кнопка нажата!")

def main(): app = Application.builder().token("YOUR_TOKEN").build() app.add_handler(CommandHandler("start", start)) app.add_handler(CallbackQueryHandler(button_callback)) app.run_polling()

if __name__ == '__main__': main() ```

Пример на JavaScript (библиотека node-telegram-bot-api)

```javascript const TelegramBot = require('node-telegram-bot-api'); const bot = new TelegramBot('YOUR_TOKEN', {polling: true});

bot.onText(/\/start/, (msg) => { const opts = { reply_markup: { inline_keyboard: [ [{text: 'Нажми меня', callback_data: 'button_pressed'}] ] } }; bot.sendMessage(msg.chat.id, 'Привет! Нажми кнопку:', opts); });

bot.on('callback_query', (query) => { const chatId = query.message.chat.id; const messageId = query.message.message_id; bot.answerCallbackQuery(query.id); bot.editMessageText('Кнопка нажата!', {chat_id: chatId, message_id: messageId}); }); ```

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

Несмотря на широкое распространение, механизм CallbackQuery имеет ряд недостатков. Главным из них является ограничение на длину данных в 64 байта, что вынуждает разработчиков использовать внешние базы данных для хранения состояния или применять сложные схемы кодирования. Кроме того, отсутствие возможности передавать бинарные данные напрямую ограничивает использование в некоторых сценариях, например, в играх с большим количеством параметров.

Также отмечается, что CallbackQuery не поддерживает автоматическое обновление состояния при длительном бездействии пользователя — бот должен сам обрабатывать тайм-ауты. В некоторых случаях это приводит к несоответствию между состоянием интерфейса и реальным состоянием на сервере.

Источники

  • Telegram Bot API Documentation — официальная документация, раздел «CallbackQuery».
  • Документация библиотеки python-telegram-bot (версия 20.x).
  • Документация библиотеки node-telegram-bot-api.
  • Статья «Telegram Bot API: Inline Keyboards and Callback Data» на сайте Medium.
  • Официальный блог Telegram — анонсы обновлений Bot API (2016–2024).

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →

Похожие материалы