Buttons in Telegram Bots

There are two types of buttons that bots can show when sending messages: inline buttons appear below the sent message and keyboard buttons are suggestions that users see near the message input.

Both kinds of buttons may be shown in multiple rows of multiple buttons. You can read more about button layouts at the bottom of this page.

Inline buttons

Inline buttons are shown together with the messages.

Callback button

A callback button is simply a button that sends an update to the bot when pressed. The bot can handle it in any way.

When a user clicks a callback button, the bot can show a notification or an alert (see the video below). To provide visual feedback to the user, the bot should typically edit the message or react in some other visible way. Until the bot reacts, the button will display a "loading" animation.

When receiving updates, the program can identify which button was pressed using a special parameter that is specified when creating the button.

URL button

A URL button acts like a link.

In Bot API, a URL button can be converted to a user mention button by specifying tg://user?ID=123456789 as the URL. In Telegram API, user mention buttons are implemented differently.

Switch-to-inline button

A switch-to-inline button opens bot inline mode. You can configure this button to open inline mode in the current chat or display a chat selection dialog first. You can also pre-fill a text query that will appear next to the bot's username (which the user can modify).

Request peer button

A request peer button allows the user to share information about one of their chats. When clicked, it displays a chat selection dialog.

You can configure this button flexibly: for example, the chat selection may include only channels with usernames or groups where the user is an admin.

Other inline buttons

There are more, rather uncommon, buttons:

• Callback game button. Opens an HTML game.
• Pay button. Used for integrated payments.
• Web view button. Opens bot web interface.
• Login URL button. Used for authorization on sites; for example, official @discussbot utilized it before Telegram introduced native comments. The button works similarly to Telegram Login Widget but doesn't require to enter the phone number and confirm the authorization.

Keyboard buttons

Unlike inline buttons, keyboard buttons are shown below the message input field (in web versions they can be accessed by clicking the command button ⌘). When pressing a keyboard button, the user simply sends its text.

In Telegram mobile apps, keyboard buttons replace the keyboard; but the user is able to hide them and see the regular keyboard again.

Apart from sending the text, a keyboard button may do one of the following:

• Ask the account phone number.
• Ask the user's geolocation.
• Open a poll creation menu.

Of course, these actions require confirmation from the user.

There is a "resize keyboard" option which determines whether the button keyboard should have flexible height. For some reason it is off by default, so the buttons look stretched:

Keyboard buttons can be shown only with sending a message. A bot can send keyboard buttons that will hide (but not disappear) after use.

In groups, keyboard buttons are visible to all members by default. Alternatively, a bot can show buttons only to mentioned users, that are:

• Users whose usernames are included in the message text
• The sender of the message to which the bot is replying

Button layouts

Both inline buttons and keyboard buttons may be aligned in multiple rows. A row may contain up to 8 buttons. The total limit of buttons shown at once is 100.

If you place multiple buttons in a row, you should make sure that their labels look OK in the mobile apps: long labels get truncated on narrow screens.