TSocial TSocial
Open in Telegram
Better in TelegramOpen in Telegram

Inline Keyboards and Callback Queries in Telegram Bots

· 4 min read · 18+ readers

Inline Keyboards and Callback Queries in Telegram Bots: TSocial guide cover card

Buttons under messages make bot icon 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 code icon 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 a t.me link icon link.
  • web_app: opens a Mini App icon (grid) 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 send icon (paper plane) 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.id for 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 megaphone icon 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

More in Build on Telegram

All topics: Build on Telegram · Guide index · Explore Telegram · About TSocial

Inline Keyboards and Callback Queries in Telegram Bots | TSocial