Inline-клавиатуры и callback-запросы

У reply-клавиатуры из прошлого урока два ограничения: она одна на чат и при нажатии пишет текст в общий поток. Inline-клавиатура телеграм бота устроена иначе: кнопки висят под конкретным сообщением, раскладок может быть сколько угодно — у каждого сообщения своя, — и нажатие не порождает нового сообщения в чате. Именно так работают опросы с голосованием по кнопке, меню с каталогом и подтверждения «Принять/Отклонить». Цена — чуть больше механики: нажатие приходит отдельным объектом CallbackQuery, у него свои поля и, главное, обязательный ответ AnswerCallbackQuery, без которого клиент показывает часы на кнопке. В этом уроке соберём клавиатуру с данными, обработаем нажатие в цикле обновлений и разберём дизайн callback_data — короткого машинного поля, которое бот читает при нажатии и которое видно в логах даже чаще, чем сами нажатия.

Структура та же по духу, что у reply: ряды и кнопки, только у кнопки два значения. NewInlineKeyboardButtonData(text, data) делает кнопку, где text — подпись, которую видит пользователь, а data — машинная строка, которую увидит только бот. Рядом живёт NewInlineKeyboardButtonURL для кнопок-ссылок: она открывает адрес и боту ничего не присылает. NewInlineKeyboardRow собирает ряд, NewInlineKeyboardMarkup(rows ...) — разметку. Главное отличие от reply здесь в разведении подписи и нагрузки: в reply подпись и полезные данные совпадают, тут они разные. Пользователь видит «Да», бот получает rsvp:yes. Ограничение Bot API: callback_data — от одного до шестидесяти четырёх байт, и это требование к дизайну: в data кладут идентификаторы и команды, а не тексты. Формат выбираете сами — «сущность:значение» надёжнее всего: vote:42, page:3, delete:101. Пользователь data не видит никогда, но она уходит в открытый API и падает в логи при отладке, поэтому секретов в ней быть не должно.

Нажатие приходит в тот же цикл обновлений, но это не Message. Update содержит поле CallbackQuery, а update.Message при этом nil — и здесь любимая паника новичка: код, который без проверки лезет в update.Message.Text, падает с nil pointer dereference на первом же нажатии. Внутри CallbackQuery четыре рабочих поля. ID — строка-идентификатор запроса, она нужна для обязательного ответа. From — пользователь, который нажал: из него берут ID для персональной логики. Message — сообщение с кнопкой: отсюда достают Chat.ID, чтобы отвечать в тот же чат. Data — то, что вы положили в callback_data. Обработку стоит строить по схеме «сначала callback, потом сообщение»: update.CallbackQuery != nil — отдельная ветка, update.Message != nil — другая. Такое разделение держит цикл плоским и не даёт nil-проверкам расползаться по всему коду.

Пока бот не вызовет AnswerCallbackQuery, клиент Telegram считает запрос незавершённым: на кнопке крутятся часы, пользователь думает, что бот завис. Отвечать нужно на каждое нажатие, и делать это быстро. В библиотеке — NewCallback(update.CallbackQuery.ID, text): текст показывается тостом над клавиатурой, лёгкое подтверждение вроде «Голос учтён». Для заметного окна есть NewCallbackWithAlert — модальное окно, которое пользователь обязан закрыть; уместно для ошибок и важных решений. Ответ уходит через bot.Request — в ответе ожидается подтверждение, а не сообщение. Практика простая: первым делом после чтения Data отвечаем на callback и только потом думаем над обработкой. Даже если бизнес-логика упала на базе, пользователь должен получить ответ нажатия, а не часы: лучше «Что-то сломалось, попробуйте позже» в тосте, чем вечный спиннер. Забытый AnswerCallbackQuery — ошибка номер один в первых inline-ботах, и лечится она раз и навсегда через defer.

Магазин стикеров на учебном боте жил неделю до первого двойного заказа. Схема была честная: inline-кнопка «Купить», в data — buy:42, по нажатию бот списывал внутренний баланс и писал «Готово». Пользователь не увидел мгновенной реакции, нажал второй раз — и списание произошло дважды: каждое нажатие это отдельный CallbackQuery, даже если кнопка на вид не изменилась. Лечение свелось к двум приёмам. Первый — EditMessageText после обработки: кнопки убираются, на их месте «Оплачено», повторное нажатие физически невозможно. Второй — идемпотентность: действие по buy:42 проверяет, не выполнено ли оно уже, и повторный callback отвечает тостом «Уже оплачено». Редактирование разобрано в шестнадцатом уроке, а принцип стоит усвоить сейчас: callback не одноразовый, пока ваш код не сделал его одноразовым.

Data — не место для текста, а адрес действия. Шестьдесят четыре байта сверху, но реальный потолок диктует здравый смысл: чем короче, тем меньше соблазн зашить лишнее. Формат «сущность:значение» — rsvp:yes, page:3, delete:101 — разбирается strings.Split-ом и читается в логах без документации. Динамические данные — идентификатор голосования, номер страницы — кладутся честно, но помните: при сбое бот логирует Data как есть, и всё, что вы туда положили, окажется в логе. Вторая половина дизайна — что бот делает после нажатия. Часто правильный ответ не новое сообщение, а правка исходного: убрать кнопки, показать «Записано», перерисовать меню на следующую страницу. Редактирование сообщений — отдельная техника шестнадцатого урока, а память для многошаговых кнопок появляется в уроке про состояние диалога.

В личке кнопка одна на диалог, в группе на неё может нажать любой участник — и это меняет дизайн. Опрос «идёте на встречу?» в группе работает прекрасно: From каждого нажатия подскажет, кто голосовал, а клики разных людей — разные CallbackQuery. Но кнопки действий — «Удалить», «Забанить», «Открыть дверь» — в общем чате превращаются в игрушку: нажать может любой, включая тех, кто сообщение не читал. Защита та же, что у команд: сверяйте cb.From.ID со списком разрешённых до выполнения действия. Второй нюанс групп — живучесть кнопок: сообщение с клавиатурой лежит в истории, и через месяц кто-то нажмёт «Принять» в мёртвой ветке. Времени жизни у кнопок нет — старение становится вашей работой, обычно правкой старого сообщения при новом состоянии.

Data — строка из вашего кода, и кажется, что доверять ей можно. Но сообщение с кнопками доступно всем, кто видит чат, и data при этом приходит любому нажавшему. Учебный бот модерации принимал delete:101 и удалял запись по номеру, не глядя, кто нажал, — пока один из студентов не открыл историю и не подчистил чужие заявки кнопкой. Формат «сущность:значение» не защита: parse:inbox в data ничего не удостоверяет. Проверка владельца обязательна на каждом действии с последствиями: cb.From.ID сверяется с автором объекта или со списком модераторов, а при отказе — тост «Это не ваша кнопка» через AnswerCallbackQuery. Заметьте: отказ тоже требует ответа на callback, иначе вместо честного отказа пользователь снова увидит часы.

У каждой inline-раскладки с выбором есть невидимая кнопка, которую забывают: отмена. Пользователь открыл меню, передумал — и застрял: кнопки живут на сообщении, а закрыть их, кроме как нажать что-то, нельзя. Спасение — кнопка «Отмена» с кодом вида menu:cancel в нижнем ряду: обработчик сбрасывает состояние из десятого урока и правит сообщение, убирая раскладку. Дешёвая привычка, которая экономит поддержку: сценарии с выбором без отмены порождают вопросы «как выйти», а вопросы — это люди, не дошедшие до цели. Исключение — опросы: там отмена не нужна, пока голосование открыто, но и оно кончается дедлайном, который вы же и задаёте.