Inline Keyboards and Callback Queries in Telegram Bots
· 4 min read · 18+ readers

Buttons under messages make bots feel like small apps. They are called inline keyboards, and when a user presses one that has callback_data, your bot receives a callback query. This guide shows how to build menus, respond properly and edit messages in place, with limits worth knowing. Check the Bot API reference for the complete field list.
Sending a keyboard
Add reply_markup with an inline_keyboard, which is a list of rows, each a list of buttons:
{
"chat_id": 123456789,
"text": "What would you like?",
"reply_markup": {
"inline_keyboard": [
[ { "text": "My links", "callback_data": "links" }, { "text": "FAQ", "callback_data": "faq" } ],
[ { "text": "Website", "url": "https://example.com" } ],
[ { "text": "Open app", "web_app": { "url": "https://app.example.com/" } } ]
]
}
}
Button kinds you will use most:
callback_data: sends data to your bot when pressed.url: opens a web page or at.melink.web_app: opens a Mini App.switch_inline_query: starts an inline query in another chat.pay: the Pay button in an invoice. See Stars payments.
Receiving the press
Telegram sends an update with
callback_query:
{
"update_id": 300,
"callback_query": {
"id": "8765",
"from": { "id": 777 },
"message": { "message_id": 41, "chat": { "id": 777 } },
"data": "faq"
}
}
Always answer it
Call answerCallbackQuery with the query id, even if you show nothing. Without it, the button keeps showing a loading indicator for the user.
{ "callback_query_id": "8765" }
You can also pass text for a small toast, or show_alert: true for a pop-up. Answer within a few seconds. Old queries expire, and answering late causes a "query is too old" error.
Update the message instead of sending a new one
Menus feel smoother when the same message changes. Use editMessageText with the chat id and message id from the callback:
{ "chat_id": 777, "message_id": 41, "text": "Frequently asked questions:",
"reply_markup": { "inline_keyboard": [[ { "text": "Back", "callback_data": "home" } ]] } }
Other editors: editMessageReplyMarkup to change only buttons, editMessageCaption for media messages and deleteMessage to clean up. Editing with identical content returns a "message is not modified" error. Ignore it.
Designing callback data
The callback_data limit is 64 bytes, so keep it short and structured:
page:guides:2
buy:order_8841
toggle:notify
Do not put secrets or large state in it. Store state on your server and send a short id. Always validate on receipt: the user can only send what your buttons offered, but old keyboards stay in chats, so a button may refer to something that no longer exists. Handle that politely.
Paging
For long lists, show five to eight items and add Previous and Next buttons that carry the page number. Edit the message in place when pressed. Disable edges: do not show Previous on page one.
Layout tips
- Two or three buttons per row, short labels.
- Put the main action first.
- Always provide a way back.
- Use clear words, not only emoji.
- Do not use many rows. Big menus feel heavy on phones.
Reply keyboards vs inline keyboards
A reply keyboard replaces the phone's keyboard with buttons that send text when pressed. An inline keyboard stays attached to one message and sends callbacks. Inline is better for menus, reply keyboards for quick answers such as Yes and No in a form.
Security and safety
- Check that the person who pressed is allowed to act. In groups, anyone can press a button, so check
from.idfor admin actions. - Make actions idempotent. Users double tap.
- Rate limit sensitive actions.
- Keep consistent text for accessibility.
See onboarding flows for menu design.
Quick checklist
- Each callback_data value is under 64 bytes and structured.
- answerCallbackQuery is called for every press.
- Menus edit the same message instead of sending new ones.
- A Back or Home button exists on every screen.
- Old buttons are handled politely if the item is gone.
- Group buttons check who pressed.
- Pages show a handful of items at a time.
- Labels are short and clear.
Accessibility and testing
Test your menu on a small phone, in dark mode and with a larger system font. Make sure labels make sense without emoji, and that important actions are not hidden behind tiny buttons. Ask someone unfamiliar with the bot to complete a task and watch where they hesitate.
Frequently asked questions
Why does the button keep spinning?
You did not call answerCallbackQuery.
Can buttons be in channel posts?
Yes, URL buttons work in channel posts sent by a bot. Callback buttons need your bot to receive updates from that chat.
Can I change one button?
Edit the whole reply_markup with the new layout.
How many buttons can I add?
Telegram limits the total number per message. Check the reference.
Related guides

Telegram Bot API Basics: Methods, Updates and Responses
How the Telegram Bot API works: URL format, JSON responses, update objects, common methods, parse modes, keyboards and how to read errors.

Telegram Bot Commands, Menus and Onboarding Flows
Design a bot that new fans can use in seconds: start message, command list, inline buttons, menus, language, error handling and a human fallback.

Telegram Inline Bots Explained: Results in Any Chat
How inline mode works: enabling it in BotFather, inline_query updates, answerInlineQuery results, caching, feedback and creator use cases, with a short example.

Create a Telegram Mini App and Register It in BotFather
Build a minimal Telegram Mini App page, include the Telegram Web App script, host it on HTTPS and register it in BotFather with a menu button or /newapp.

Common Telegram Bot Errors and How to Fix Them
A troubleshooting table for Bot API errors: 400, 401, 403, 409, 429 and 5xx, with causes and fixes for polling, webhooks, groups, payments and Mini Apps.

A Telegram Webhook on AWS Lambda or a Small Server
Two ways to receive Telegram updates: an AWS Lambda function URL and a tiny Node server behind HTTPS, with secret token checks, fast replies and queues.
More in Build on Telegram
- Add a Bot as Channel Admin and Post to Your Channel
- Bot Privacy Mode and Group Admin Rights Explained
- BotFather Commands: What Each One Does
- Connect a Bot to Your Telegram Business Account (Chatbot Mode)
All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial