Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/grammy/convenience/keyboard.ts>Keyboard

The Telegram Bot Framework.
grammyjs/grammY
Very Popular
Latest
class Keyboard
import { Keyboard } from "https://deno.land/x/grammy@v1.31.0/convenience/keyboard.ts";

Use this class to simplify building a custom keyboard (something like this: https://core.telegram.org/bots/features#keyboards).

// Build a custom keyboard:
const keyboard = new Keyboard()
  .text('A').text('B').row()
  .text('C').text('D')

// Now you can send it like so:
await ctx.reply('Here is your custom keyboard!', {
  reply_markup: keyboard
})

If you already have some source data which you would like to turn into a keyboard button object, you can use the static equivalents which every button has. You can use them to create a two-dimensional keyboard button array. The resulting array can be turned into a keyboard instance.

const button = Keyboard.text('push my buttons')
const array = [[button]]
const keyboard = Keyboard.from(array)

If you want to create text buttons only, you can directly use a two-dimensional string array and turn it into a keyboard.

const data = [['A', 'B'], ['C', 'D']]
const keyboard = Keyboard.from(data)

Be sure to check out the documentation on custom keyboards in grammY.

Constructors

new
Keyboard(keyboard?: KeyboardButton[][])

Initialize a new Keyboard with an optional two-dimensional array of KeyboardButton objects. This is the nested array that holds the custom keyboard. It will be extended every time you call one of the provided methods.

Properties

optional
input_field_placeholder: string

Placeholder to be shown in the input field when the keyboard is active.

optional
is_persistent: boolean

Requests clients to always show the keyboard when the regular keyboard is hidden. Defaults to false, in which case the custom keyboard can be hidden and opened with a keyboard icon.

optional
one_time_keyboard: boolean

Hide the keyboard after a button is pressed.

optional
resize_keyboard: boolean

Resize the current keyboard according to its buttons. Usually, this will make the keyboard smaller.

optional
selective: boolean

Show the current keyboard only to those users that are mentioned in the text of the message object.

Methods

add(...buttons: KeyboardButton[])

Allows you to add your own KeyboardButton objects if you already have them for some reason. You most likely want to call one of the other methods.

append(...sources: KeyboardSource[])

Appends the buttons of the given keyboards to this keyboard. If other options are specified in these keyboards, they will be ignored.

build()

Returns the keyboard that was build. Note that it doesn't return resize_keyboard or other options that may be set. You don't usually need to call this method. It is no longer useful.

clone(keyboard?: KeyboardButton[][])

Creates and returns a deep copy of this keyboard.

Optionally takes a new grid of buttons to replace the current buttons. If specified, only the options will be cloned, and the given buttons will be used instead.

oneTime(isEnabled?)

Make the current keyboard one-time. See https://grammy.dev/plugins/keyboard#one-time-custom-keyboards for more details.

Keyboards are non-one-time by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-one-time.

persistent(isEnabled?)

Make the current keyboard persistent. See https://grammy.dev/plugins/keyboard#persistent-keyboards for more details.

Keyboards are not persistent by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to not persist.

placeholder(value: string)

Set the current keyboard's input field placeholder. See https://grammy.dev/plugins/keyboard#input-field-placeholder for more details.

requestChat(
text: string,
requestId: number,
options?: Omit<KeyboardButtonRequestChat, "request_id">,
)

Adds a new request chat button. When the user presses the button, a list of suitable users will be opened. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

requestContact(text: string)

Adds a new contact request button. The user's phone number will be sent as a contact when the button is pressed. Available in private chats only.

requestLocation(text: string)

Adds a new location request button. The user's current location will be sent when the button is pressed. Available in private chats only.

requestPoll(text: string, type?: KeyboardButtonPollType["type"])

Adds a new poll request button. The user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only.

requestUsers(
text: string,
requestId: number,
options?: Omit<KeyboardButtonRequestUsers, "request_id">,
)

Adds a new request users button. When the user presses the button, a list of suitable users will be opened. Tapping on any number of users will send their identifiers to the bot in a “users_shared” service message. Available in private chats only.

resized(isEnabled?)

Make the current keyboard resized. See https://grammy.dev/plugins/keyboard#resize-custom-keyboard for more details.

Keyboards are non-resized by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-resized.

row(...buttons: KeyboardButton[])

Adds a 'line break'. Call this method to make sure that the next added buttons will be on a new row.

You may pass a number of KeyboardButton objects if you already have the instances for some reason. You most likely don't want to pass any arguments to row.

selected(isEnabled?)

Make the current keyboard selective. See https://grammy.dev/plugins/keyboard#selectively-send-custom-keyboards for more details.

Keyboards are non-selective by default, use this function to enable it (without any parameters or pass true). Pass false to force the keyboard to be non-selective.

text(text: string)

Adds a new text button. This button will simply send the given text as a text message back to your bot if a user clicks on it.

toFlowed(columns: number, options?: FlowOptions)

Creates a new keyboard with the same buttons but reflowed into a given number of columns as if the buttons were text elements. Optionally, you can specify if the flow should make sure to fill up the last row.

This method is idempotent, so calling it a second time will effectively clone this keyboard without reordering the buttons.

Here are some examples.

original    flowed
[  a  ]  ~> [  a  ]    (4 columns)

            [  a  ]
[a b c]  ~> [  b  ]    (1 column)
            [  c  ]

[ a b ]     [a b c]
[ c d ]  ~> [ d e ]    (3 columns)
[  e  ]

[ a b ]     [abcde]
[  c  ]  ~> [  f  ]    (5 columns)
[d e f]

[a b c]     [  a  ]
[d e f]  ~> [b c d]    (3 colums, { fillLastRow: true })
[g h i]     [e f g]
[  j  ]     [h i j]
toTransposed()

Creates a new keyboard that contains the transposed grid of buttons of this keyboard. This means that the resulting keyboard has the rows and columns flipped.

Note that buttons can only span multiple columns, but never multiple rows. This means that if the given arrays have different lengths, some buttons might flow up in the layout. In these cases, transposing a keyboard a second time will not undo the first transposition.

Here are some examples.

original    transposed
[  a  ]  ~> [  a  ]

            [  a  ]
[a b c]  ~> [  b  ]
            [  c  ]

[ a b ]     [a c e]
[ c d ]  ~> [ b d ]
[  e  ]

[ a b ]     [a c d]
[  c  ]  ~> [ b e ]
[d e f]     [  f  ]
webApp(text: string, url: string)

Adds a new web app button. The Web App that will be launched when the user presses the button. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

Static Methods

from(source: KeyboardSource): Keyboard

Turns a two-dimensional keyboard button array into a keyboard instance. You can use the static button builder methods to create keyboard button objects.

requestChat(
text: string,
requestId: number,
options?: Omit<KeyboardButtonRequestChat, "request_id">,
): KeyboardButton.RequestChatButton

Creates a new request chat button. When the user presses the button, a list of suitable users will be opened. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

requestContact(text: string): KeyboardButton.RequestContactButton

Creates a new contact request button. The user's phone number will be sent as a contact when the button is pressed. Available in private chats only.

requestLocation(text: string): KeyboardButton.RequestLocationButton

Creates a new location request button. The user's current location will be sent when the button is pressed. Available in private chats only.

requestPoll(text: string, type?: KeyboardButtonPollType["type"]): KeyboardButton.RequestPollButton

Creates a new poll request button. The user will be asked to create a poll and send it to the bot when the button is pressed. Available in private chats only.

requestUsers(
text: string,
requestId: number,
options?: Omit<KeyboardButtonRequestUsers, "request_id">,
): KeyboardButton.RequestUsersButton

Creates a new request users button. When the user presses the button, a list of suitable users will be opened. Tapping on any number of users will send their identifiers to the bot in a “users_shared” service message. Available in private chats only.

text(text: string): KeyboardButton.CommonButton

Creates a new text button. This button will simply send the given text as a text message back to your bot if a user clicks on it.

webApp(text: string, url: string): KeyboardButton.WebAppButton

Creates a new web app button. The Web App that will be launched when the user presses the button. The Web App will be able to send a “web_app_data” service message. Available in private chats only.