{"id":21810487,"url":"https://github.com/alexandercerutti/node-telegram-keyboard-wrapper","last_synced_at":"2025-04-13T22:11:22.285Z","repository":{"id":44411519,"uuid":"120967026","full_name":"alexandercerutti/node-telegram-keyboard-wrapper","owner":"alexandercerutti","description":"A support to manage keyboards and force replies in Telegram via bots","archived":false,"fork":false,"pushed_at":"2022-12-12T03:51:49.000Z","size":190,"stargazers_count":51,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T07:52:08.679Z","etag":null,"topics":["node-js","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexandercerutti.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-09T23:31:24.000Z","updated_at":"2025-03-14T14:56:56.000Z","dependencies_parsed_at":"2023-01-27T13:00:51.209Z","dependency_job_id":null,"html_url":"https://github.com/alexandercerutti/node-telegram-keyboard-wrapper","commit_stats":{"total_commits":106,"total_committers":2,"mean_commits":53.0,"dds":"0.037735849056603765","last_synced_commit":"7b8531a5dfa63376b3edfec8a529041246cde1a7"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandercerutti%2Fnode-telegram-keyboard-wrapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandercerutti%2Fnode-telegram-keyboard-wrapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandercerutti%2Fnode-telegram-keyboard-wrapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandercerutti%2Fnode-telegram-keyboard-wrapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexandercerutti","download_url":"https://codeload.github.com/alexandercerutti/node-telegram-keyboard-wrapper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248788925,"owners_count":21161727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["node-js","telegram","telegram-bot"],"created_at":"2024-11-27T13:36:02.571Z","updated_at":"2025-04-13T22:11:22.262Z","avatar_url":"https://github.com/alexandercerutti.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Node telegram keyboard wrapper\n\nThis library aims to provide a set of classes to improve the creation of keyboards and setup for force-reply in Telegram bots.\n\nBuilt upon [yagop's node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api), it can work with any Node.js Bot Api wrapper, as it exports Telegram Bot APIs-compliant JSON structures.\n\n\u003e ⚠ v3.0.0 of this library is a major rewrite that is not retro-compatible. It doesn't export anymore an object with `reply_markup`. From now on, it will export just the content for `reply_markup`, which will vary from keyboard to keyboard. ⚠\n\n---\n\n## Architecture\n\nThe philosophy behind this library, since v3, is to make it easier, through a series of state-less classes, to create the JSON structures to represent Rows, Buttons and the whole keyboards.\n\nTo achieve this, both ReplyKeyboard and InlineKeyboard classes and Row class extend the native Array interface.\n\nTherefore you can do every operation you want just like you were acting on Arrays.\n\n---\n\n### Looking for previous version?\n\nI hope you don't, but if you really need it, [here it is](https://github.com/alexandercerutti/node-telegram-keyboard-wrapper/tree/v2.0.1).\n\n---\n\n### Install\n\n```sh\n$ npm install --save node-telegram-keyboard-wrapper\n```\n\n---\n\n### Example\n\nIn examples folder, an example bot is available. It requires a bot token to be passed as argument.\n\n```sh\n$ npm run example -- 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\n```\n\nThen just type `/replyKeyboard` (and answer or click to hide), `/inlineKeyboard` (and click to trigger) or `/forceReply` in your Telegram client to see the wrapper in action.\n\n---\n\n## API Reference\n\n\u003cbr\u003e\n\n- [ForceReply](#forcereply)\n  - [`static` .getMarkup](#user-content-static-getmarkup)\n- [Row](#user-content-row-extends-arrayprototype)\n  - [.clone](#user-content-clone)\n- [InlineKeyboard](#user-content-inlinekeyboard-extends-arrayprototype)\n  - [.getMarkup](#user-content-getmarkup)\n  - [.clone](#user-content-clone-1)\n- [InlineKeyboardButton](#user-content-inlinekeyboardbutton)\n  - [.clone](#user-content-clone-2)\n- [ReplyKeyboard](#user-content-replykeyboard-extends-arrayprototype)\n  - [.getMarkup](#user-content-getmarkup-1)\n  - [.remove](#user-content-remove)\n  - [.clone](#user-content-clone-3)\n- [KeyboardButton](#user-content-keyboardbutton)\n  - [.clone](#user-content-clone-4)\n\n### ForceReply\n\n#### `static` `.getMarkup`\n\n```typescript\nForceReply.getMarkup(selective: boolean = false): Object;\n\nForceReply.getMarkup();\nForceReply.getMarkup(true);\n```\n\nUse this method to export the structure to be sent to `reply_markup`.\n\n**Arguments**:\n\n| Argument  |  Type   | Required | Default Value |\n| --------- | :-----: | :------: | :-----------: |\n| selective | boolean |  false   |    `false`    |\n\n---\n\n### Row (extends `Array.prototype`)\n\n```typescript\nnew Row\u003cR extends InlineKeyboardButton | KeyboardButton\u003e(...values: R[]): Row;\n```\n\nUse this class to define a row to which buttons can be appended to.\n\nPush this class into an InlineKeyboard or a ReplyKeyboard to let them create the structure.\n\nThis class extends native arrays and, therefore, allows every operation you can perform on Arrays to be performed on this.\n\n**Arguments**:\n\nInherited from Array's constructor.\n\n---\n\n#### `.clone`\n\n```typescript\nRow.prototype.clone(): Row\u003cR\u003e;\n\nconst row = new Row\u003cKeyboardButton\u003e();\nconst clone = row.clone();\n\nrow !== clone; // true;\n```\n\nCreates a copy of the row and clones all its children / buttons.\n\n---\n\n### InlineKeyboard (extends `Array.prototype`)\n\n```typescript\nnew InlineKeyboard(...values: Row\u003cInlineKeyboardButton\u003e[]): InlineKeyboard;\n```\n\nUse this class to create a container for InlineKeyboards.\n\nThis class extends the native Array interface, therefore every operation you can perform on Arrays is allowed to be performed on this.\n\n**Arguments**:\n\nInherited from Array's constructor.\n\n---\n\n#### `.getMarkup`\n\n```typescript\nInlineKeyboard.prototype.getMarkup(): Object;\n\nconst keyboard = new InlineKeyboard();\nkeyboard.getMarkup();\n```\n\nUse this method to export the structure to be sent to `reply_markup`.\n\n**Throws if no rows got pushed in the object**.\n\n**Arguments**:\n\nnone.\n\n---\n\n#### `.clone`\n\n```typescript\nInlineKeyboard.prototype.clone(): InlineKeyboard;\n\nconst keyboard = new InlineKeyboard();\nconst clone = row.clone();\n\nkeyboard !== clone; // true;\n```\n\nCreates a copy of the keyboard, a copy of all of its row and a clone of all of their children / buttons.\n\n---\n\n### InlineKeyboardButton\n\n```typescript\nnew InlineKeyboardButton\u003cS extends string\u003e(text: string, exclusiveKey: S, exclusiveValue: T[S]): InlineKeyboardButton;\n```\n\nUse this method to create a button to be pushed in a Row.\nAs per the Telegram Bot API Documentation, each InlineKeyboardButton **must have only one of the optional properties**.\n\n**Arguments**:\n\n| Argument       |       Type       | Required | Default Value | Description                                                |\n| -------------- | :--------------: | :------: | :-----------: | ---------------------------------------------------------- |\n| text           |      string      |   true   |       -       | The visual string to be shown on the button.               |\n| exclusiveKey   | S extends string |   true   |       -       | The required key for this button.                          |\n| exclusiveValue |       T[S]       |   true   |       -       | the value for `exclusiveKey` (it differs from key to key). |\n\nFor the valid values of `exclusiveKey` and `exclusiveValue` refer to [InlineKeyboardButton](https://core.telegram.org/bots/api#inlinekeyboardbutton);\n\n**Example**:\n\n```typescript\nconst row = new Row\u003cInlineKeyboardButton\u003e();\n\nrow.push(\n\tnew InlineKeyboardButton(\"My text\", \"url\", \"https://localhost:8080/\"),\n\tnew InlineKeyboardButton(\n\t\t\"My text 2\",\n\t\t\"callback_data\",\n\t\t\"any data between 1 and 64 bytes\"\n\t)\n);\n```\n\n---\n\n#### `.clone`\n\n```typescript\nInlineKeyboardButton.prototype.clone(): InlineKeyboardButton;\n\nconst button = new InlineKeyboardButton();\nconst clone = button.clone();\n\nbutton !== clone; // true;\n```\n\nCreates a copy of the button and objects inside it.\n\n---\n\n### ReplyKeyboard (extends `Array.prototype`)\n\n```typescript\nnew ReplyKeyboard(...values: Row\u003cKeyboardButton\u003e[]): ReplyKeyboard;\n```\n\nUse this class to create a new keyboard that is going to show up under the text area in your Telegram client.\n\nThis class extends the native Array interface, therefore every operation you can perform on Arrays is allowed to be performed on this.\n\n**Arguments**:\n\nInherited from Array's constructor.\n\n---\n\n#### `.getMarkup`\n\n```typescript\nReplyKeyboard.prototype.getMarkup(): Object;\n\nconst keyboard = new ReplyKeyboard();\nkeyboard.getMarkup();\n```\n\nUse this method to export the structure to be sent to `reply_markup` for opening the keyboard.\n\n**Throws if no rows got pushed in the object**.\n\n**Arguments**:\n\n| Argument                  |  Type   | Required | Default Value |\n| ------------------------- | :-----: | :------: | :-----------: |\n| options                   | Object  |  false   |     `{}`      |\n| options.resize_keyboard   | boolean |  false   |  `undefined`  |\n| options.one_time_keyboard | boolean |  false   |  `undefined`  |\n| options.selective         | boolean |  false   |  `undefined`  |\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\nThis list might get outdated. The arguments are used as they are passed.\nRefer to [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) for the complete list, eventually.\n\n\u003cbr /\u003e\n\n---\n\n#### `.remove`\n\n```typescript\nReplyKeyboard.prototype.remove(): Object;\n\nconst keyboard = new ReplyKeyboard();\nkeyboard.remove();\n```\n\nUse this method to export the structure to be sent to `reply_markup` for closing definitely the keyboard.\n\n**Arguments**:\n\n| Argument  |  Type   | Required | Default Value |\n| --------- | :-----: | :------: | :-----------: |\n| selective | boolean |  false   |    `false`    |\n\n\u003cbr /\u003e\n\n---\n\n#### `.clone`\n\n```typescript\nReplyKeyboard.prototype.clone(): ReplyKeyboard;\n\nconst keyboard = new ReplyKeyboard();\nconst clone = keyboard.clone();\n\nkeyboard !== clone; // true;\n```\n\nCreates a copy of the keyboard, a copy of all of its row and a clone of all of their children / buttons.\n\n---\n\n### KeyboardButton\n\n```typescript\nnew KeyboardButton\u003cS extends string\u003e(text: string, options: Options): KeyboardButton;\n```\n\nUse this method to create a button to be pushed in a Row.\n\n**Arguments**:\n\n| Argument                  |        Type         | Required | Default Value | Description                                  |\n| ------------------------- | :-----------------: | :------: | :-----------: | -------------------------------------------- |\n| text                      |       string        |   true   |       -       | The visual string to be shown on the button. |\n| options                   |       Object        |  false   |     `{}`      | The options for this button.                 |\n| options.request_contact   |       boolean       |  false   |  `undefined`  | -                                            |\n| options.request_location  |       boolean       |  false   |  `undefined`  | -                                            |\n| options.request_poll      |       Object        |  false   |  `undefined`  | -                                            |\n| options.request_poll.type | \"quiz\" \\| \"regular\" |   true   |  `undefined`  | -                                            |\n\n\u003cbr /\u003e\n\u003cbr /\u003e\n\n**Example**:\n\n```typescript\nconst row = new Row\u003cKeyboardButton\u003e();\n\nrow.push(\n\tnew KeyboardButton(\"My text 1\", {\n\t\trequest_location: true,\n\t\trequest_contact: false,\n\t})\n);\n```\n\n---\n\n#### `.clone`\n\n```typescript\nInlineKeyboardButton.prototype.clone(): InlineKeyboardButton;\n\nconst button = new InlineKeyboardButton();\nconst clone = button.clone();\n\nbutton !== clone; // true;\n```\n\nCreates a copy of the button and objects inside it.\n\n---\n\n### Testing\n\nTests are build upon Jasmine Unit suite.\nRun these commands to test changes after have cloned the repository:\n\n```sh\n$ npm install\n\n$ npm run build # to build from Typescript\n$ npm run build:spec # to build tests\n$ npm test # to both build tests and run them\n```\n\n---\n\nAny contribution, is welcome. Made with ❤️ in Italy.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandercerutti%2Fnode-telegram-keyboard-wrapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexandercerutti%2Fnode-telegram-keyboard-wrapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandercerutti%2Fnode-telegram-keyboard-wrapper/lists"}