Keyboard

The Keyboard API allows you to create interactive keyboards with various button types for VK messages. Use Keyboard for static button definitions and KeyboardBuilder for dynamic keyboard construction.

Keyboard Class

Static methods for creating keyboards and buttons.

Static Methods

builder()

Returns a new KeyboardBuilder instance for constructing keyboards.

const keyboard = Keyboard.builder()
  .textButton({ label: 'Start' })
  .row()
  .textButton({ label: 'Help' });

Returns: KeyboardBuilder

keyboard(rows)

Assembles a keyboard from an array of button rows.

rows

(IKeyboardProxyButton | IKeyboardProxyButton[])[]

required

Array of button rows. Each row can be a single button or an array of buttons.

const keyboard = Keyboard.keyboard([
  Keyboard.textButton({ label: 'Option 1' }),
  [Keyboard.textButton({ label: 'A' }), Keyboard.textButton({ label: 'B' })],
]);

Returns: KeyboardBuilder

Button Factory Methods

textButton(options)

Creates a text button that can be colored.

options

IKeyboardTextButtonOptions

required

Configuration for the text button

Show IKeyboardTextButtonOptions

label

string

required

Button label (max 40 characters)

color

ButtonColor | ButtonColorUnion

Button color (default: SECONDARY_COLOR)

payload

ButtonPayload

Custom data payload (max 255 characters when stringified)

const button = Keyboard.textButton({
  label: 'Buy Coffee',
  payload: { command: 'buy', item: 'coffee' },
  color: Keyboard.POSITIVE_COLOR,
});

urlButton(options)

Creates a URL button that opens a link.

options

IKeyboardURLButtonOptions

required

Configuration for the URL button

Show IKeyboardURLButtonOptions

label

string

required

Button label (max 40 characters)

url

string

required

The URL to open when clicked

payload

ButtonPayload

Custom data payload (max 255 characters when stringified)

const button = Keyboard.urlButton({
  label: 'Visit Site',
  url: 'https://example.com',
});

locationRequestButton(options)

Creates a button that requests user location. Occupies the entire keyboard width.

options

IKeyboardLocationRequestButtonOptions

required

Configuration for the location button

Show IKeyboardLocationRequestButtonOptions

payload

ButtonPayload

Custom data payload (max 255 characters when stringified)

const button = Keyboard.locationRequestButton({
  payload: { command: 'order_delivery' },
});

payButton(options)

Creates a VK Pay button. Occupies the entire keyboard width.

options

IKeyboardVKPayButtonOptions

required

Configuration for the VK Pay button

Show IKeyboardVKPayButtonOptions

payload

ButtonPayload

required

Custom data payload

hash

KeyboardVKPayHash | string

required

Payment parameters or hash string

const button = Keyboard.payButton({
  payload: {},
  hash: {
    action: 'transfer-to-group',
    group_id: 1,
    aid: 10,
  },
});

applicationButton(options)

Creates a VK Apps button. Occupies the entire keyboard width.

options

IKeyboardApplicationButtonOptions

required

Configuration for the VK Apps button

Show IKeyboardApplicationButtonOptions

label

string

required

Button label (max 40 characters)

appId

number

required

VK Apps application identifier

ownerId

number

Community ID where the app is installed

hash

string

Navigation hash for the application

const button = Keyboard.applicationButton({
  label: 'Open App',
  appId: 6232540,
  ownerId: -157525928,
});

callbackButton(options)

Creates a callback button that triggers events without sending a message.

options

IKeyboardCallbackButtonOptions

required

Configuration for the callback button

Show IKeyboardCallbackButtonOptions

label

string

required

Button label (max 40 characters)

color

ButtonColor | ButtonColorUnion

Button color (default: SECONDARY_COLOR)

payload

ButtonPayload

Custom data payload (max 255 characters when stringified)

const button = Keyboard.callbackButton({
  label: 'Like',
  payload: { action: 'like', id: 123 },
  color: Keyboard.PRIMARY_COLOR,
});

Button Colors

Button color constants for text and callback buttons.

SECONDARY_COLOR

ButtonColor.SECONDARY

White button (#FFFFFF) - indicates secondary action

PRIMARY_COLOR

ButtonColor.PRIMARY

Blue button (#5181B8) - indicates main action

NEGATIVE_COLOR

ButtonColor.NEGATIVE

Red button (#E64646) - indicates dangerous/negative action

POSITIVE_COLOR

ButtonColor.POSITIVE

Green button (#4BB34B) - indicates agreement/confirmation

KeyboardBuilder Class

Builder class for constructing keyboards with a fluent API.

Properties

isOneTime

boolean

Whether the keyboard closes after pressing a button (default: false)

isInline

boolean

Whether the keyboard is attached inline to the message (default: false)

Methods

textButton(options)

Adds a text button to the current row.

options

IKeyboardTextButtonOptions

required

Button configuration (same as Keyboard.textButton)

builder.textButton({
  label: 'Buy Coffee',
  payload: { command: 'buy', item: 'coffee' },
  color: Keyboard.POSITIVE_COLOR,
});

Returns: this (for chaining)

urlButton(options)

Adds a URL button. May create a new row if current row has 2+ buttons.

options

IKeyboardURLButtonOptions

required

Button configuration

Returns: this (for chaining)

locationRequestButton(options)

Adds a location request button. May create a new row if current row has 2+ buttons.

options

IKeyboardLocationRequestButtonOptions

required

Button configuration

Returns: this (for chaining)

payButton(options)

Adds a VK Pay button. May create a new row if current row has 2+ buttons.

options

IKeyboardVKPayButtonOptions

required

Button configuration

Returns: this (for chaining)

applicationButton(options)

Adds a VK Apps button. May create a new row if current row has 2+ buttons.

options

IKeyboardApplicationButtonOptions

required

Button configuration

Returns: this (for chaining)

callbackButton(options)

Adds a callback button to the current row.

options

IKeyboardCallbackButtonOptions

required

Button configuration

Returns: this (for chaining)

row()

Saves the current row and starts a new row.

builder
  .textButton({ label: 'Button 1' })
  .textButton({ label: 'Button 2' })
  .row()
  .textButton({ label: 'Button 3' });

Returns: this (for chaining) Note: Maximum 5 buttons per row.

oneTime(enabled)

Sets whether the keyboard closes after a button press.

enabled

boolean

default:"true"

Enable one-time mode

builder.oneTime(); // Enable
builder.oneTime(false); // Disable

Returns: this (for chaining)

inline(enabled)

Sets whether the keyboard is inline.

enabled

boolean

default:"true"

Enable inline mode

builder.inline(); // Enable
builder.inline(false); // Disable

Returns: this (for chaining) Note: Inline keyboards have a maximum of 6 rows, regular keyboards have 10.

clone()

Clones the builder with all settings and buttons.

const clone = builder.clone();

Returns: KeyboardBuilder

toString()

Returns the JSON string representation for the VK API.

const keyboardJson = builder.toString();

Returns: string

Usage Examples

Simple Keyboard

const keyboard = Keyboard.builder()
  .textButton({ label: 'Start', color: Keyboard.POSITIVE_COLOR })
  .row()
  .textButton({ label: 'Help' })
  .toString();

await vk.api.messages.send({
  peer_id: userId,
  message: 'Welcome!',
  keyboard,
});

Multi-Row Keyboard with Callbacks

const keyboard = Keyboard.builder()
  .callbackButton({
    label: 'Like',
    payload: { action: 'like' },
    color: Keyboard.PRIMARY_COLOR,
  })
  .callbackButton({
    label: 'Dislike',
    payload: { action: 'dislike' },
    color: Keyboard.NEGATIVE_COLOR,
  })
  .row()
  .urlButton({ label: 'Website', url: 'https://example.com' })
  .inline()
  .toString();

One-Time Keyboard

const keyboard = Keyboard.builder()
  .textButton({ label: 'Yes', color: Keyboard.POSITIVE_COLOR })
  .textButton({ label: 'No', color: Keyboard.NEGATIVE_COLOR })
  .oneTime()
  .toString();

Using Static keyboard() Method

const keyboard = Keyboard.keyboard([
  Keyboard.textButton({ label: 'Option 1' }),
  [
    Keyboard.textButton({ label: 'A' }),
    Keyboard.textButton({ label: 'B' }),
    Keyboard.textButton({ label: 'C' }),
  ],
  Keyboard.urlButton({ label: 'More Info', url: 'https://example.com' }),
]).toString();

Type Definitions

ButtonColor

enum ButtonColor {
  SECONDARY = 'secondary',
  PRIMARY = 'primary',
  NEGATIVE = 'negative',
  POSITIVE = 'positive',
}

ButtonPayload

type ButtonPayload = object | string;

Payload must not exceed 255 characters when JSON stringified.

VK Pay Hash Types

Show IVKPayPayToGroup

action

'pay-to-group'

required

group_id

number

required

Group ID to receive payment

amount

number

required

Payment amount in rubles (minimum 1)

description

string

Payment description

data

string

Arbitrary payload

aid

string | number

required

Application ID

Show IVKPayTransferToGroup

action

'transfer-to-group'

required

group_id

number

required

Group ID to receive transfer

aid

string | number

required

Application ID

Constraints

Maximum label length: 40 characters
Maximum payload size: 255 characters (JSON stringified)
Maximum buttons per row: 5
Maximum rows for inline keyboards: 6
Maximum rows for regular keyboards: 10

Core Classes

Structures

Utilities

​Keyboard

​Keyboard Class

​Static Methods

​builder()

​keyboard(rows)

​Button Factory Methods

​textButton(options)

​urlButton(options)

​locationRequestButton(options)

​payButton(options)

​applicationButton(options)

​callbackButton(options)

​Button Colors

​KeyboardBuilder Class

​Properties

​Methods

​textButton(options)

​urlButton(options)

​locationRequestButton(options)

​payButton(options)

​applicationButton(options)

​callbackButton(options)

​row()

​oneTime(enabled)

​inline(enabled)

​clone()

​toString()

​Usage Examples

​Simple Keyboard

​Multi-Row Keyboard with Callbacks

​One-Time Keyboard

​Using Static keyboard() Method

​Type Definitions

​ButtonColor

​ButtonPayload

​VK Pay Hash Types

​Constraints

Build docs developers (and LLMs) love

Keyboard

Keyboard Class

Static Methods

builder()

keyboard(rows)

Button Factory Methods

textButton(options)

urlButton(options)

locationRequestButton(options)

payButton(options)

applicationButton(options)

callbackButton(options)

Button Colors

KeyboardBuilder Class

Properties

Methods

textButton(options)

urlButton(options)

locationRequestButton(options)

payButton(options)

applicationButton(options)

callbackButton(options)

row()

oneTime(enabled)

inline(enabled)

clone()

toString()

Usage Examples

Simple Keyboard

Multi-Row Keyboard with Callbacks

One-Time Keyboard

Using Static keyboard() Method

Type Definitions

ButtonColor

ButtonPayload

VK Pay Hash Types

Constraints