Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Messages and Embeds

Buttons and Inline Keyboards

Add interactive buttons to Telegram and Discord bots - inline keyboards, callback_data, action rows, button styles, custom_id design, select menus and updating messages - with runnable builders and a vote example.

Typing commands is fine for power users, but buttons are friendlier: one tap to confirm, vote, change page or pick an option. Both platforms attach buttons to messages. Telegram calls them inline keyboards; Discord calls them message components. The two work the same way at heart: each button carries a small piece of data, and when someone presses it your bot receives an event containing that data. Everything interesting is in how you design the data and how you react.

Telegram inline keyboards

An inline keyboard is a reply_markup parameter holding an array of rows, each an array of buttons:

JSON
{
  "chat_id": 5,
  "text": "Delete this item?",
  "reply_markup": {
    "inline_keyboard": [
      [{ "text": "Yes", "callback_data": "del:42:yes" }, { "text": "No", "callback_data": "del:42:no" }],
      [{ "text": "Open site", "url": "https://example.com" }]
    ]
  }
}

A button has text plus exactly one action: callback_data (your bot gets a callback_query update), url (opens a link), web_app (opens a Mini App), switch_inline_query and a few others. Limits: callback_data is 1 to 64 bytes (bytes, not characters, so emoji and non-Latin letters count more), up to 8 buttons per row, and 100 buttons per message.

When a user presses a button you receive an update with callback_query: { id, from, message, data }. You must call answerCallbackQuery (with optional text for a small toast or show_alert: true for a popup), and you usually edit the original message with editMessageText or editMessageReplyMarkup to reflect the new state.

There is also a reply keyboard (reply_markup: { keyboard: [[...]], resize_keyboard: true }) that replaces the user's typing keyboard; presses arrive as ordinary text messages. It suits fixed menus and the special request_contact or request_location buttons. Remove it with { remove_keyboard: true }.

Discord components

Components live in a message's components array. The top level must be action rows (type: 1), each holding up to 5 buttons or one select menu. A message can have at most 5 action rows.

JSON
{
  "content": "Delete this item?",
  "components": [{
    "type": 1,
    "components": [
      { "type": 2, "style": 4, "label": "Delete", "custom_id": "del:42:yes" },
      { "type": 2, "style": 2, "label": "Cancel", "custom_id": "del:42:no" },
      { "type": 2, "style": 5, "label": "Docs", "url": "https://example.com" }
    ]
  }]
}

Button style values: 1 primary (blurple), 2 secondary (gray), 3 success (green), 4 danger (red), 5 link. Buttons of styles 1 to 4 need a custom_id (up to 100 characters); link buttons need a url and no custom_id, and they do not send any event. Add disabled: true to gray a button out.

Pressing a non-link button sends your bot an interaction of type 3 (message component), with data.custom_id and the message it was attached to. You respond within 3 seconds with response type 7 (UPDATE_MESSAGE, edit the original) or 6 (DEFERRED_UPDATE, acknowledge only) or 4 (a new reply, often ephemeral).

Select menus (type: 3) offer a dropdown of up to 25 options with min_values and max_values; the interaction's data.values holds the chosen option values. Discord also offers user, role and channel select menus (types 5 to 8) that list real server objects.

Designing button data

Both callback_data and custom_id are tiny, so they work like a URL path: action:target:argument. Rules that keep bots reliable:

  1. Namespace by action. like:42 and del:42 must not collide. Route on the prefix.
  2. Store ids, not state. Put an item id in the data and look up the rest in your database. Do not encode whole objects.
  3. Mind the size. 64 bytes (Telegram) is easy to exceed with long ids. Use short ids.
  4. Never trust the data. Anyone who can see the button can press it (even in a group), and clients can send crafted data. Check that the pressing user is allowed to do what the button does.
  5. Expect stale buttons. Users press buttons on old messages after a redeploy. Unknown actions should answer politely rather than crash.
Node.js Keyboard builders with limit checks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The second failing case is the classic Telegram surprise: 40 characters of รฉ are 80 bytes. If you need to carry non-ASCII text, store it server-side and put a short id in the button.

Reacting to presses: a vote example

Here is a complete loop: a poll message with three buttons, a handler that parses the data, records one vote per user, and returns the updated message. The same logic works on both platforms, because the handler is a pure function from (state, user, data) to a result; only the transport differs.

Node.js A one-vote-per-user poll with buttons

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

On Telegram the handler's toast goes into answerCallbackQuery({ callback_query_id, text }) and refresh triggers editMessageText with the new text and keyboard. On Discord, refresh becomes an interaction response of type 7 with the new content and components, while a toast becomes a type 4 ephemeral message (flags: 64). Telegram edits fail with 400 message is not modified if the new content is identical, so only edit when something actually changed.

Disable a button after use (disabled: true on Discord, or remove the keyboard on Telegram) for one-shot actions such as "Confirm delete". It prevents double submissions and makes the state obvious to everyone watching.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the Telegram callback_data limit?

    callback_data must be 1 to 64 bytes. Non-ASCII characters take more than one byte each.
  2. 2. Which Discord button style needs a url instead of a custom_id?

    Link buttons (style 5) open a URL and never send an interaction, so they have a url and no custom_id.
  3. 3. Why should button data hold ids rather than full objects?

    64 bytes or 100 characters leave little room. Store state server-side and look it up by id.
  4. 4. A button is pressed on a message from before your last deployment, with an action your new code does not know. What should happen?

    Always answer the callback or interaction, even to say that the action is unknown, so the client does not show a spinner or failure.
  5. 5. Why check who pressed a button?

    Buttons in shared chats are visible to everyone, so authorise the action based on the presser's identity.

Summary

  • Telegram: reply_markup.inline_keyboard rows of buttons; callback_data up to 64 bytes; answer every callback_query and edit the message.
  • Discord: action rows (max 5) of buttons or one select menu; custom_id up to 100 characters; respond with UPDATE_MESSAGE (7) or a new reply (4).
  • Design button data like action:id:arg, keep ids short and state server-side.
  • Authorise the presser, handle stale buttons and avoid no-op edits.
  • Keep the vote or menu logic in pure functions so both platforms share it.

Next: Files and Uploads