telegraf-ctx-menu

This is a package designed to intergrate with the Telegraf telegram bot API library. The idea behind the package is to allow users to generate complex and dynamic inline-keyboards to go with their bots

Quick Start

const bot = new Telegraf<MyContext>(token);
bot.use(session());
const menuFactory = new MenuFactory<MyContext>();

const itemsMenu = menuFactory.menu({
	command: "items",
	parseMode: "MarkdownV2",
	description: "View your available items",
	dialogFunction: (ctx) => {
		return "Hello, here is where you select your items"
	},
	buttons: [
		[
			{
				label: 'Add item',
				action: (ctx) => {
					ctx.answerCbQuery();
					ctx.reply('You have added an item');
				}
			},
			{
				label: 'Remove item',
				action: (ctx) => {
					ctx.anserCbQuery();
				},
				promptAction: (ctx) => {
					doSomethingWithUserResponse();
				}
			}
		],
		[
			{
				label: 'Cancel',
				action: (ctx) => {
					ctx.anserCbQuery();
				},
			}
		]
	]
})

itemsMenu.register(bot);

Usage

To create menus, a MenuFactory is used, this stores the typing of your bot's context. Once that is set up you can use the menu method in order to generate menu objects.

To use the menu method, several arguments must be provided and the Telegraf session middleware must be registered with the bot.

Once you have your menu created, use the register method of your menu to register the bot to that menu. This method binds some internal middleware for listening to callback actions as well as handling user prompting

Required arguments

• command -> The command that will be used to envoke this menu
• description -> The description of the command (used for telegram setting commands)
• dialogFunction -> A function which returns a string. This is called to generate and update the text of the menu's message
• buttons -> An array or array of arrays of buttons

Optional arguments

• parseMode -> The parse mode that messages should be sent with
• onFirstSend -> Function called when a new iteration of this menu is sent to the user. (Useful for resettings session information)

Buttons

Buttons are objects with a few fields

Required button fields

• label -> The text displayed on the button or a function which returns a string to display on the button
• action -> A callback function which recieves the context of the callback update which corresponds to the button

Optional fields

• promptAction -> Assumes that the pressed button prompted the user for some input. This function is called on the next text message update recieved from the user
• submenu -> A new array or array of array of buttons which replaces the current inline keyboard with this new submenu when the action function is called and returns a markup indicator (See action return types)
• hidden -> A callback function which recieves the context of the last update to the menu. Returns a boolean (true to hide the button, false to display the button)
• payload -> An element of data which will be set in ctx.state.payload before action or promptAction are called for use in the callback

Action return types

Both button action and promptAction functions may return either nothing or an object with fields { markup?: UpdateOption, editDialog?: boolean, returnUp?: number (See SUBMENU_RETURN_SPECIFIC)} The markup field takes an UpdateOption enum member as it's type. These ENUM members are:

• CLOSE -> Remove the menu buttons from the menu message
• MARKUP -> Regenerate the inline keyboard being displayed, recalling the label functions
• SUBMENU -> Update the menu with the submenu linked to this button
• SUBMENU_RETURN -> Go up a level of submenu, returning to the parent menu
• SUBMENU_RETURN_ROOT -> Update the menu with the inline keyboard of the top-level keyboard
• SUBMEUN_RETURN_SPECIFIC -> Return up a provided number of submenus. The number of submenus is specified with returnUp in the callback return type
• NEW_SUBMENU -> (See dynamic submenus)

Dynamic submenus

Dynamic submenus are inline keyboard variations which are generated at runtime rather than at buildtime. These are generally used to display and interact with user specific data. Dynamic submenus can be generated as part of an action or promptAction callback. They take the same shape as the buttons field though they are set in ctx.state.newSubmenu rather than as part of a function call. In order for the MenuHandler to recognize and build the submenu, the callback must return at least { markup: UpdateOption.NEW_SUBMENU } otherwise the new keyboard will not be recognized.