Кнопки в телеграм боте
Бот отвечает на команду /start, а кнопки под сообщением не появляются. Такая ситуация знакома многим, кто впервые создаёт бота в Telegram. В этом материале давайте разберём, как работают кнопки в Telegram-боте и чем inline-кнопки, которые прикреплены к сообщению, отличаются от reply-кнопок, заменяющих клавиатуру.
Inline и reply: разница кнопок в телеграм боте
Бот отвечает на /start текстом, а под сообщением пусто. Обычно причина простая: клавиатуру не передали вместе с сообщением или выбрали не тот вид кнопок. Чтобы понять, что именно пошло не так, сначала нужно разобраться, как устроены кнопки в Telegram-боте.
Два вида кнопок в телеграм боте
Telegram предлагает два вида кнопок, и работают они по-разному. Inline-кнопки (от англ. inline, «в строке») живут под сообщением бота и отправляются вместе с ним. Reply-кнопки (от англ. reply, «ответ») заменяют клавиатуру внизу экрана, то есть то место, где обычно печатают текст.
Оба вида задаются через параметр reply_markup. Это необязательный аргумент метода отправки сообщения. В него вы передаёте описание клавиатуры, и Telegram выводит её вместе с текстом. Если параметра нет, сообщение уходит без кнопок.
Классы, которые создают клавиатуру
В библиотеках для Python за inline-кнопки отвечают классы InlineKeyboardMarkup и InlineKeyboardButton. Клавиатуру внизу экрана создают ReplyKeyboardMarkup и KeyboardButton. Названия похожи, поэтому их легко перепутать. Запомните правило: в классах со словом Inline кнопка привязана к сообщению, а в остальных кнопка привязана к полю ввода.
markup = InlineKeyboardMarkup([
[InlineKeyboardButton("Цены", callback_data="prices")]
])
bot.send_message(chat_id, "Выберите действие:", reply_markup=markup)
markup = ReplyKeyboardMarkup([
[KeyboardButton("Каталог"), KeyboardButton("Мой заказ")]
], resize_keyboard=True)
bot.send_message(chat_id, "Выберите действие:", reply_markup=markup)
Обратите внимание: у inline-кнопки есть callback_data, а у reply-кнопки только текст. Именно это определяет, что произойдёт при нажатии.
Когда что использовать
В таблице собрано главное различие между видами кнопок.
| Вид кнопок | Где находится кнопка | Как срабатывает нажатие | Передаются ли данные | Когда уместно |
|---|---|---|---|---|
| Inline | Под сообщением бота, внутри чата | Бот получает callback_query, текст в чат не попадает | Да, скрытые данные в callback_data до 64 байт | Выбор варианта в конкретном сообщении: «Цены», «Оплатить», «Далее» |
| Reply | Внизу экрана, вместо клавиатуры | Текст кнопки уходит в чат как сообщение пользователя | Только текст кнопки, если не запрошен контакт или геолокация | Постоянное меню: «Каталог», «Мой заказ», «Связаться с менеджером» |
Событие callback_query — это служебный сигнал, с которым бот получает информацию о нажатии на кнопку. Он приходит отдельно от сообщений чата, поэтому пользователь его не видит. Reply-кнопка работает наоборот: нажатие выглядит как обычное сообщение, и такой текст остаётся в истории чата бота.
Что будет дальше в статье
Ниже разбирается минимальный рабочий пример: команда /start и три inline-кнопки. Токен, который выдаёт BotFather, понадобится уже на первом шаге. Затем идут три причины, почему кнопка не реагирует на нажатие: нет обработчика, callback_data не совпадает и не вызван answer. Отдельно показано, как обойти лимит в 64 байта. В конце рассмотрены бизнес-сценарии: меню стоматологической клиники и интернет-магазина.
Для владельца бизнеса суть такая: каждая кнопка ведёт клиента на следующий шаг, от выбора услуги до заявки менеджеру.
Создание кнопок в телеграм боте на aiogram
Давайте перейдём к практике. Ниже разобран минимальный рабочий пример: бот отвечает на команду /start и показывает три inline-кнопки. Понадобятся Python, библиотека aiogram третьей версии и доступ к Telegram. Каждый шаг добавляет одну деталь, поэтому код можно собирать постепенно и проверять результат после каждого изменения.
Шаг 1. Создание бота начинается с BotFather, официального бота Telegram для управления другими ботами. Отправьте ему команду /newbot, задайте имя и username, который должен заканчиваться на bot. В ответ придёт токен бота, строка вида 123456789:AAH... Это API-токен, по которому Telegram понимает, какому боту адресованы запросы. Не публикуйте его в открытом доступе, иначе кто угодно сможет управлять вашим ботом. Вставьте токен в код:
BOT_TOKEN = "123456789:AAH..."
Шаг 2. Запуск бота отвечает за polling. Это режим, при котором бот сам регулярно спрашивает у Telegram, есть ли новые обновления. Когда пользователь пишет сообщение или нажимает кнопку, Telegram ставит это событие в очередь, а бот забирает его при следующем запросе. Соберите каркас:
import asyncio
from aiogram import Bot, Dispatcher
BOT_TOKEN = "123456789:AAH..."
bot = Bot(token=BOT_TOKEN)
dp = Dispatcher()
async def main():
await dp.start_polling(bot)
if __name__ == "__main__":
asyncio.run(main())
Сохраните файл и запустите его командой python bot.py. Пока обработчиков нет, бот на /start промолчит. Это нормально: он работает и ждёт обновлений.
Шаг 3. Команды start приходят боту как обновление типа message, то есть как обычное сообщение от пользователя. Обработчик объявляем через async def. Фильтр CommandStart говорит aiogram вызывать функцию только для команды start, а не для любого текста. Метод message.answer отправляет ответ в тот же чат, откуда пришла команда.
from aiogram.filters import CommandStart
from aiogram.types import Message
@dp.message(CommandStart())
async def cmd_start(message: Message):
await message.answer("Сейчас покажу меню.")
Шаг 4. Теперь создаем клавиатуру. У inline-кнопки два основных поля. Поле text задаёт текст кнопки, который видит пользователь. Поле callback_data хранит скрытую строку, которую бот получит при нажатии. Её длина не должна превышать 64 байта, иначе Telegram откажется показывать клавиатуру. Строки кнопок собираются в список списков: каждый внутренний список выводится отдельной строкой. Функция ниже возвращает меню из трёх кнопок:
from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
def get_start_keyboard() -> InlineKeyboardMarkup:
return InlineKeyboardMarkup(inline_keyboard=[
[InlineKeyboardButton(text="Услуги", callback_data="services")],
[InlineKeyboardButton(text="Цены", callback_data="prices")],
[InlineKeyboardButton(text="Контакты", callback_data="contacts")],
])
Чтобы меню появилось, добавьте в функцию cmd_start параметр reply_markup. Это одна новая строка, остальной код остаётся прежним:
await message.answer("Выберите раздел:", reply_markup=get_start_keyboard())
Не запоминайте, а поймите: inline-кнопки живут под сообщением бота и привязаны именно к нему.
Шаг 5. Нажатие на кнопку приходит как обновление типа callback_query. Обработчик ищет совпадение по полю data, в котором лежит callback_data нажатой кнопки. Совпадение обязательно. Если в фильтре записано services, а в кнопке service, нажатие никуда не попадёт, и бот промолчит. Вызов callback.answer() убирает индикатор загрузки на кнопке. Без него кнопка некоторое время крутится, и пользователь решит, что бот завис.
from aiogram import F
from aiogram.types import CallbackQuery
@dp.callback_query(F.data == "services")
async def on_services(callback: CallbackQuery):
await callback.answer()
await callback.message.answer("Услуги: чистка, лечение, имплантация.")
Всё это укладывается в модель событий. Telegram присылает update, то есть одно событие: сообщение, нажатие на кнопку или что-то другое. Внутри update лежит конкретный тип, например message или callback_query. Aiogram сверяет тип и фильтры, находит подходящую функцию-обработчик и вызывает её. Каждый обработчик отвечает только за своё событие, поэтому код остаётся понятным.
В pyTelegramBotAPI, библиотеке telebot, логика такая же: события приходят, обработчики подбираются по фильтрам. Меняется синтаксис. Вместо декоратора dp.message пишут @bot.message_handler, для кнопок используют @bot.callback_query_handler с параметром func, а функции объявляются без async def.
Шаг 6. Добавить кнопку в меню можно без правки уже работающего кода. Допишите новую строку в список, задайте уникальный callback_data и добавьте отдельный обработчик для нового нажатия:
[InlineKeyboardButton(text="Записаться", callback_data="book")],
[InlineKeyboardButton(text="Наш сайт", url="https://example.com")],
@dp.callback_query(F.data == "book")
async def on_book(callback: CallbackQuery):
await callback.answer()
await callback.message.answer("Напишите, на какое время вам удобно.")
Кнопка со ссылкой работает иначе. Поле url открывает страницу сразу, без участия бота, поэтому обработчик для неё не нужен.
Чтобы расширить меню до нескольких кнопок в одной строке, перечислите их через запятую внутри одного внутреннего списка:
[InlineKeyboardButton(text="Да", callback_data="yes"), InlineKeyboardButton(text="Нет", callback_data="no")],
Если всё получилось, бот на /start показывает меню, а каждое нажатие запускает свой обработчик.
Кнопка не работает: ошибки callback_data и обработчиков
Когда бот молчит после нажатия, причин обычно три. Telegram присылает боту служебное событие callback_query: оно сообщает, что пользователь нажал inline-кнопку (кнопку под сообщением). Внутри события лежит строка callback_data, по которой бот понимает, какая именно кнопка нажата. Если одно из звеньев этой цепочки сломано, нажатие уходит в пустоту. Разберём каждое звено: симптом, быструю проверку и правку.
Нет обработчика callback_query
Симптом: кнопка на месте, но после нажатия в чате ничего не происходит, и в логах нет записи о нажатии. Быстрая проверка: найдите функцию, которая принимает CallbackQuery и стоит под декоратором callback_query. Если такой функции нет, бот получает нажатие и просто его пропускает.
Правка: добавьте обработчик. Для каждой кнопки обычно пишут отдельную функцию:
@dp.callback_query(F.data == "prices")
async def on_prices(callback: CallbackQuery):
await callback.answer()
await callback.message.answer("Стрижка стоит 1000 рублей.")
Убедитесь, что роутер с обработчиком подключён к диспетчеру. Обработчик, который не подключён, для Telegram не существует.
Не совпадает callback_data
Симптом: обработчик есть, но не срабатывает. Обычно строка в кнопке и строка в фильтре отличаются регистром, пробелом или лишним словом. Для бота это разные значения, и совпадения не будет.
Быстрая проверка: сравните значение callback_data в кнопке со значением в F.data и посмотрите на регистр и пробелы в конце строки.
Правка: вынесите строку в константу, чтобы кнопка и обработчик брали одно и то же значение:
BOOK = "book"
keyboard = InlineKeyboardMarkup(inline_keyboard=[
[InlineKeyboardButton(text="Записаться", callback_data=BOOK)]
])
@dp.callback_query(F.data == BOOK)
async def on_book(callback: CallbackQuery):
await callback.answer()
Не вызван answer
Симптом: на кнопке появляется значок загрузки и не исчезает. Telegram ждёт от бота подтверждения, что нажатие обработано. Пока подтверждения нет, индикатор крутится.
Быстрая проверка: есть ли в обработчике вызов callback.answer().
Правка: вызовите его первой строкой функции. Если обработчик падает с ошибкой до answer, индикатор тоже останется, поэтому вызов в начале надёжнее. Можно сразу показать короткое уведомление: await callback.answer("Принято"). Так пользователь видит реакцию, даже пока бот отправляет сообщение.
Ошибка BUTTON_DATA_INVALID
Bot API возвращает ошибку BUTTON_DATA_INVALID, когда callback_data не проходит проверку. Почти всегда это значит одно: строка слишком длинная. Лимит Telegram составляет 64 байта. Считаются именно байты, а не символы. Русская буква в UTF-8 занимает два байта, поэтому слово «категория» из восьми букв весит шестнадцать байтов. Проверить длину можно так: len(data.encode("utf-8")).
Решение: в callback_data передавайте короткий ключ, а полные данные храните на стороне бота. Это может быть словарь, база данных или файл:
PRODUCTS = {
"p1": {"name": "Кроссовки", "size": 42},
"p2": {"name": "Ботинки", "size": 43},
}
keyboard = InlineKeyboardMarkup(inline_keyboard=[
[InlineKeyboardButton(text="Кроссовки, 42", callback_data="p1")]
])
@dp.callback_query(F.data.in_(list(PRODUCTS)))
async def on_product(callback: CallbackQuery):
await callback.answer()
item = PRODUCTS[callback.data]
await callback.message.answer(f"Вы выбрали: {item['name']}, размер {item['size']}.")
Словарь в памяти теряется при перезапуске бота. Для рабочего проекта данные лучше хранить в базе.
Почему кнопки не появляются
Если сообщение пришло без кнопок, проверьте параметр reply_markup. В нём передаётся клавиатура. Без него сообщение отправится, но клавиатуры под ним не будет. Частая ошибка: клавиатуру собрали, а в вызове message.answer или bot.send_message о ней забыли.
Вторая причина связана с типом клавиатуры. Inline-кнопки передаются через InlineKeyboardMarkup, а reply-кнопки через ReplyKeyboardMarkup. В reply-клавиатуре нет поля callback_data, поэтому кнопка с callback_data в этом случае работает иначе. Нажатие на reply-кнопку отправляет в чат её текст, и бот получает обычное сообщение.
Проверьте и вложенность списков. Каждая кнопка в отдельном списке даёт отдельную строку, а кнопки в одном списке выстраиваются в ряд. Пустой список inline_keyboard=[] даёт сообщение без меню.
Ошибки в тексте сообщения и названии кнопки
Этот пункт недооценивают чаще всего. Для reply-кнопок текст самой кнопки становится сообщением пользователя, поэтому фильтр F.text должен совпадать с названием кнопки до последнего символа. Если на кнопке написано «Записаться», а в фильтре «Записатся», обработчик не сработает. Опечатка в тексте сообщения, к которому привязана клавиатура, тоже мешает: пользователь видит не то, что вы проверяли при тестах.
Риски на проде
Если бот уже работает, не меняйте callback_data у кнопок. Старые сообщения с кнопками остаются в чатах пользователей, и нажатие на них отправит боту прежнюю строку. Если обработчика для неё больше нет, кнопка перестанет работать, и пользователь решит, что бот сломан.
Поступайте так: оставьте старый обработчик рядом с новым, например F.data.in_({"book", "record"}). Старый вариант уберите позже, когда старые сообщения точно не нужны. Так вы поправите логику и не потеряете клиентов.
Кнопки для бизнеса: меню, заявки и частые вопросы
Как выглядит меню для клиники и магазина?
Для клиники и магазина меню строится по одной схеме: несколько кнопок на главном экране и понятный путь к заказу. Стоматологическая клиника выводит кнопки «Записаться», «Цены» и «Адрес». Нажатие на «Записаться» запускает сценарий бота, который спрашивает дату и время. Интернет-магазин добавляет кнопки «Каталог», «Мой заказ» и «Связаться с менеджером». Каждая кнопка здесь — шаг клиента к заказу, а не украшение.
Как заявка проходит от нажатия кнопки до менеджера?
Работа такого меню выглядит просто. Клиент нажимает кнопку, бот ведёт его по шагам, а поля ввода собирают ответы. Номер телефона бот запрашивает отдельным шагом, и заявка с ним уходит менеджеру. Сценарий продумайте заранее: какие вопросы задать, какие ответы принять и какой вариант клиент может выбрать сам. Так пользователи смогут дойти до оформления без менеджера, если каждый шаг понятен.
Нужна ли дорогая разработка для базового меню?
Многие владельцы думают, что меню требует дорогой разработки. На деле базовое меню строится тем же кодом, что показан выше. Нужны обработчик команды start, список кнопок и обработчик нажатий. Новая кнопка добавляется несколькими строками, а сценарий разбивается на шаги, как обычный диалог. Сложные интеграции с оплатой и CRM подключаются позже, поэтому на старте бюджет почти не растёт.
Что важно запомнить про inline, reply и нажатия?
Inline-кнопки живут под сообщением и отправляют боту callback_data при нажатии. Reply-кнопки заменяют клавиатуру внизу экрана и присылают текст, который должен совпасть с фильтром F.text до последнего символа. Любое нажатие требует обработчика, а на callback нужно ответить через answer. Тип кнопок выбирайте по задаче: постоянное меню для навигации и inline для действий внутри одного сообщения.
Что проверить, если кнопки не работают?
Если кнопка не появляется, проверьте, что клавиатура передана в отправку сообщения. Inline и reply можно совмещать, но поддержка станет сложнее. Ошибка BUTTON_DATA_INVALID означает слишком длинный callback_data, поэтому передавайте короткий ID. Разработчики могут скопировать пример. Владельцы бизнеса могут перечислить частые вопросы клиентов и обсудить проект.