GramIO API Reference / @gramio/keyboards/dist / Keyboard

Class: Keyboard

Defined in: keyboards/index.d.ts:178

ReplyKeyboardMarkup builder

This object represents a custom keyboard with reply options (see Introduction to bots for details and examples).

[Documentation]

Extends

BaseKeyboardConstructor<TelegramKeyboardButton>

Constructors

Constructor

new Keyboard(featureFlags?): Keyboard

Defined in: keyboards/index.d.ts:48

Parameters

Parameter	Type
`featureFlags?`	`KeyboardFeatureFlags`

Returns

Keyboard

Inherited from

BaseKeyboardConstructor.constructor

Properties

Property	Modifier	Type	Inherited from	Defined in
`currentRow`	`protected`	`TelegramKeyboardButton`[]	`BaseKeyboardConstructor`.`currentRow`	keyboards/index.d.ts:46
`featureFlags`	`protected`	`KeyboardFeatureFlags`	`BaseKeyboardConstructor`.`featureFlags`	keyboards/index.d.ts:47
`options`	`public`	`object`	-	keyboards/index.d.ts:179
`options.isOneTime`	`public`	`boolean`	-	keyboards/index.d.ts:180
`options.isPersistent`	`public`	`boolean`	-	keyboards/index.d.ts:181
`options.isResized`	`public`	`boolean`	-	keyboards/index.d.ts:182
`options.isSelective`	`public`	`boolean`	-	keyboards/index.d.ts:183
`options.placeholder`	`public`	`string`	-	keyboards/index.d.ts:184
`rows`	`protected`	`TelegramKeyboardButton`[][]	`BaseKeyboardConstructor`.`rows`	keyboards/index.d.ts:45

Accessors

keyboard

Get Signature

get protected keyboard(): T[][]

Defined in: keyboards/index.d.ts:52

Returns

T[][]

Inherited from

BaseKeyboardConstructor.keyboard

Methods

add()

add(...buttons): this

Defined in: keyboards/index.d.ts:127

Allows you to add multiple buttons in raw format.

Parameters

Parameter	Type
...`buttons`	`TelegramKeyboardButton`[]

Returns

this

Example

const labels = ["some", "buttons"];

new InlineKeyboard()
    .add({ text: "raw button", callback_data: "payload" })
    .add(InlineKeyboard.text("raw button by InlineKeyboard.text", "payload"))
    .add(...labels.map((x) => InlineKeyboard.text(x, `${x}payload`)));

Inherited from

BaseKeyboardConstructor.add

addIf()

addIf(condition, ...buttons): this

Defined in: keyboards/index.d.ts:147

Allows you to dynamically substitute buttons depending on something

Parameters

Parameter	Type
`condition`	`boolean` \| (`options`) => `boolean`
...`buttons`	`TelegramKeyboardButton`[]

Returns

this

Example

const labels = ["some", "buttons"];
const isAdmin = true;

new InlineKeyboard()
    .addIf(1 === 2, { text: "raw button", callback_data: "payload" })
    .addIf(
        isAdmin,
        InlineKeyboard.text("raw button by InlineKeyboard.text", "payload")
    )
    .addIf(
        ({ index, rowIndex }) => rowIndex === index,
        ...labels.map((x) => InlineKeyboard.text(x, `${x}payload`))
    );

Inherited from

BaseKeyboardConstructor.addIf

build()

build(): TelegramReplyKeyboardMarkup

Defined in: keyboards/index.d.ts:348

Return TelegramReplyKeyboardMarkup as object

Returns

TelegramReplyKeyboardMarkup

columns()

columns(length?): this

Defined in: keyboards/index.d.ts:75

Allows you to limit the number of columns in the keyboard.

Parameters

Parameter	Type
`length?`	`number`

Returns

this

Example

new InlineKeyboard()
    .columns(1)
    .text("first row", "payload")
    .text("second row", "payload");
    .text("third row", "payload");

Inherited from

BaseKeyboardConstructor.columns

combine()

combine(keyboard): this

Defined in: keyboards/index.d.ts:342

Allows you to combine keyboards. Only keyboards are combined. You need to call the .row() method to line-break after combine.

Parameters

Parameter	Type
`keyboard`	`TelegramReplyKeyboardMarkup` \| `TelegramKeyboardButton`[][] \| { `toJSON`: () => `TelegramReplyKeyboardMarkup`; }

Returns

this

Example

new Keyboard()
			.combine(new Keyboard().text("first"))
			.row()
			.combine(new Keyboard().text("second").row().text("third"))

filter()

filter(fn?): this

Defined in: keyboards/index.d.ts:99

A handler that helps filter keyboard buttons

Parameters

Parameter	Type
`fn?`	`ButtonsIterator`<`TelegramKeyboardButton`>

Returns

this

Example

new InlineKeyboard()
    .filter(({ button }) => button.callback_data !== "hidden")
    .text("button", "pass")
    .text("button", "hidden")
    .text("button", "pass");

Inherited from

BaseKeyboardConstructor.filter

matrix()

matrix(rows, columns, fn): this

Defined in: keyboards/index.d.ts:167

Allows you to create a button matrix.

Parameters

Parameter	Type
`rows`	`number`
`columns`	`number`
`fn`	`CreateButtonIterator`<`TelegramKeyboardButton`>

Returns

this

Example

import { randomInt } from "node:crypto";

const bomb = [randomInt(0, 9), randomInt(0, 9)] as const;

new InlineKeyboard().matrix(10, 10, ({ rowIndex, index }) =>
   InlineKeyboard.text(
       rowIndex === bomb[0] && index === bomb[1] ? "💣" : "ㅤ",
       "payload"
   )
);

Inherited from

BaseKeyboardConstructor.matrix

oneTime()

oneTime(isEnabled?): this

Defined in: keyboards/index.d.ts:290

Requests clients to hide the keyboard as soon as it's been used. The keyboard will still be available, but clients will automatically display the usual letter-keyboard in the chat - the user can press a special button in the input field to see the custom keyboard again. Defaults to false.

Parameters

Parameter	Type
`isEnabled?`	`boolean`

Returns

this

Example

new Keyboard().text("some text").oneTime(); // to enable
new Keyboard().text("some text").oneTime(false); // to disable

pattern()

pattern(pattern?): this

Defined in: keyboards/index.d.ts:114

An array with the number of columns per row. Allows you to set a "template"

Parameters

Parameter	Type
`pattern?`	`number`[]

Returns

this

Example

new InlineKeyboard()
    .pattern([1, 3, 2])
    .text("1", "payload")
    .text("2", "payload")
    .text("2", "payload")
    .text("2", "payload")
    .text("3", "payload")
    .text("3", "payload");

Inherited from

BaseKeyboardConstructor.pattern

persistent()

persistent(isEnabled?): this

Defined in: keyboards/index.d.ts:299

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.

Parameters

Parameter	Type
`isEnabled?`	`boolean`

Returns

this

Example

new Keyboard().text("some text").persistent(); // to enable
new Keyboard().text("some text").persistent(false); // to disable

placeholder()

placeholder(value?): this

Defined in: keyboards/index.d.ts:308

The placeholder to be shown in the input field when the keyboard is active; 1-64 characters

Parameters

Parameter	Type
`value?`	`string`

Returns

this

Example

new Keyboard().text("some text").placeholder("some text"); // to enable
new Keyboard().text("some text").placeholder(); // to disable

requestChat()

requestChat(text, requestId, options?, buttonOptions?): this

Defined in: keyboards/index.d.ts:221

If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`requestId`	`number`
`options?`	`Omit`<`TelegramKeyboardButtonRequestChat`, `"request_id"` \| `"chat_is_channel"`> & `object`
`buttonOptions?`	`ButtonOptions`

Returns

this

Example

new Keyboard().requestChat("gramio", 255, {
    chat_is_forum: true,
});

requestContact()

requestContact(text, options?): this

Defined in: keyboards/index.d.ts:237

If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

this

Example

new Keyboard().requestContact("some button text");

requestLocation()

requestLocation(text, options?): this

Defined in: keyboards/index.d.ts:249

If True, the user's current location will be sent when the button is pressed. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

this

Example

new Keyboard().requestLocation("some button text");

requestPoll()

requestPoll(text, type?, options?): this

Defined in: keyboards/index.d.ts:263

If specified, 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.

If quiz is passed, the user will be allowed to create only polls in the quiz mode. If regular is passed, only regular polls will be allowed. Otherwise, the user will be allowed to create a poll of any type.

Parameters

Parameter	Type
`text`	`string`
`type?`	`string`
`options?`	`ButtonOptions`

Returns

this

Example

new Keyboard().requestPoll("some button text", "quiz");

requestUsers()

requestUsers(text, requestId, options?, buttonOptions?): this

Defined in: keyboards/index.d.ts:207

If specified, pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a “users_shared” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`requestId`	`number`
`options?`	`Omit`<`TelegramKeyboardButtonRequestUsers`, `"request_id"`>
`buttonOptions?`	`ButtonOptions`

Returns

this

Example

new Keyboard().requestUsers("some button text", 228, {
    user_is_premium: true,
});

resetHelpers()

resetHelpers(): this

Defined in: keyboards/index.d.ts:168

Returns

this

Inherited from

BaseKeyboardConstructor.resetHelpers

resized()

resized(isEnabled?): this

Defined in: keyboards/index.d.ts:319

!Note Keyboard is resized by default! For disable it you can use .resized(false)

Requests clients to resize the keyboard vertically for optimal fit (e.g., make the keyboard smaller if there are just two rows of buttons). Defaults to false, in which case the custom keyboard is always of the same height as the app's standard keyboard.

Parameters

Parameter	Type
`isEnabled?`	`boolean`

Returns

this

Example

new Keyboard().text("some text").resized(); // to enable
new Keyboard().text("some text").resized(false); // to disable

row()

row(): this

Defined in: keyboards/index.d.ts:63

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

Returns

this

Example

new InlineKeyboard()
    .text("first row", "payload")
    .row()
    .text("second row", "payload");

Inherited from

BaseKeyboardConstructor.row

selective()

selective(isEnabled?): this

Defined in: keyboards/index.d.ts:330

Use this parameter if you want to show the keyboard to specific users only. Targets: 1) users that are @mentioned in the text of the Message object; 2) if the bot's message is a reply to a message in the same chat and forum topic, sender of the original message.

Example: A user requests to change the bot's language, bot replies to the request with a keyboard to select the new language. Other users in the group don't see the keyboard.

Parameters

Parameter	Type
`isEnabled?`	`boolean`

Returns

this

Example

new Keyboard().text("some text").selective(); // to enable
new Keyboard().text("some text").selective(false); // to disable

text()

text(text, options?): this

Defined in: keyboards/index.d.ts:193

Text of the button. It will be sent as a message when the button is pressed

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

this

Example

new Keyboard().text("some button text");

toJSON()

toJSON(): TelegramReplyKeyboardMarkup

Defined in: keyboards/index.d.ts:352

Serializing a class into an TelegramReplyKeyboardMarkup object (used by JSON.stringify)

Returns

TelegramReplyKeyboardMarkup

webApp()

webApp(text, url, options?): this

Defined in: keyboards/index.d.ts:277

If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`url`	`string`
`options?`	`ButtonOptions`

Returns

this

Example

new Keyboard().webApp("some button text", "https://...");

wrap()

wrap(fn?): this

Defined in: keyboards/index.d.ts:87

A custom handler that controls row wrapping.

Parameters

Parameter	Type
`fn?`	`ButtonsIterator`<`TelegramKeyboardButton`>

Returns

this

Example

new InlineKeyboard()
    .wrap(({ button }) => button.callback_data === "2")
    .text("first row", "1")
    .text("first row", "1");
    .text("second row", "2");

Inherited from

BaseKeyboardConstructor.wrap

requestChat()

static requestChat(text, requestId, options?, buttonOptions?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:227

If specified, pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a “chat_shared” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`requestId`	`number`
`options?`	`Omit`<`TelegramKeyboardButtonRequestChat`, `"request_id"` \| `"chat_is_channel"`> & `object`
`buttonOptions?`	`ButtonOptions`

Returns

TelegramKeyboardButton

requestContact()

static requestContact(text, options?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:241

If True, the user's phone number will be sent as a contact when the button is pressed. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

TelegramKeyboardButton

requestLocation()

static requestLocation(text, options?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:253

If True, the user's current location will be sent when the button is pressed. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

TelegramKeyboardButton

requestPoll()

static requestPoll(text, type?, options?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:269

If specified, 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.

Parameters

Parameter	Type
`text`	`string`
`type?`	`string`
`options?`	`ButtonOptions`

Returns

TelegramKeyboardButton

requestUsers()

static requestUsers(text, requestId, options?, buttonOptions?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:211

If specified, pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a “users_shared” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`requestId`	`number`
`options?`	`Omit`<`TelegramKeyboardButtonRequestUsers`, `"request_id"`>
`buttonOptions?`	`ButtonOptions`

Returns

TelegramKeyboardButton

text()

static text(text, options?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:197

Text of the button. It will be sent as a message when the button is pressed

Parameters

Parameter	Type
`text`	`string`
`options?`	`ButtonOptions`

Returns

TelegramKeyboardButton

webApp()

static webApp(text, url, options?): TelegramKeyboardButton

Defined in: keyboards/index.d.ts:281

If specified, the described Web App will be launched when the button is pressed. The Web App will be able to send a “web_app_data” service message. Available in private chats only.

Parameters

Parameter	Type
`text`	`string`
`url`	`string`
`options?`	`ButtonOptions`

Returns

TelegramKeyboardButton

Class: Keyboard ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Inherited from ​

Properties ​

Accessors ​

keyboard ​

Get Signature ​

Returns ​

Inherited from ​

Methods ​

add() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

addIf() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

build() ​

Returns ​

columns() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

combine() ​

Parameters ​

Returns ​

Example ​

filter() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

matrix() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

oneTime() ​

Parameters ​

Returns ​

Example ​

pattern() ​

Parameters ​

Returns ​

Example ​

Inherited from ​

persistent() ​

Parameters ​

Returns ​

Example ​

placeholder() ​

Parameters ​

Returns ​

Example ​

requestChat() ​

Parameters ​

Returns ​

Example ​

requestContact() ​

Parameters ​

Returns ​

Example ​

requestLocation() ​

Parameters ​

Returns ​

Example ​

requestPoll() ​

Parameters ​

Returns ​

Example ​

requestUsers() ​

Parameters ​

Class: Keyboard

Extends

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

Accessors

keyboard

Get Signature

Returns

Inherited from

Methods

add()

Parameters

Returns

Example

Inherited from

addIf()

Parameters

Returns

Example

Inherited from

build()

Returns

columns()

Parameters

Returns

Example

Inherited from

combine()

Parameters

Returns

Example

filter()

Parameters

Returns

Example

Inherited from

matrix()

Parameters

Returns

Example

Inherited from

oneTime()

Parameters

Returns

Example

pattern()

Parameters

Returns

Example

Inherited from

persistent()

Parameters

Returns

Example

placeholder()

Parameters

Returns

Example

requestChat()

Parameters

Returns

Example

requestContact()

Parameters

Returns

Example

requestLocation()

Parameters

Returns

Example

requestPoll()

Parameters

Returns

Example

requestUsers()

Parameters