telegram-inline-keyboard-builder 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +146 -121
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,187 +1,212 @@
|
|
|
1
|
-
|
|
1
|
+
 [](https://www.npmjs.com/package/telegram-inline-keyboard-builder) [](https://www.npmjs.com/package/telegram-inline-keyboard-builder) [](LICENSE) 
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Inline Keyboard Builder (v2) Universal inline keyboard builder for Telegram Bots.
|
|
4
|
+
Produces **pure Telegram Bot API compliant JSON**, usable with **any library** (Telegraf, node-telegram-bot-api, Pyrogram, Aiogram, Puregram, Telebot…).
|
|
4
5
|
|
|
5
|
-
>
|
|
6
|
+
> Version 2 removes adapters and focuses on a single universal output:
|
|
7
|
+
> **valid `inline_keyboard` JSON as expected by Telegram API**.
|
|
6
8
|
|
|
9
|
+
---
|
|
10
|
+
## 🚀 Key Features - Fluent & chainable API - Library-agnostic (no adapters, no dependencies)
|
|
7
11
|
|
|
12
|
+
- Produces **pure Telegram inline keyboard JSON**
|
|
13
|
+
- Auto-wrap & row control - Works with **any Telegram framework**
|
|
14
|
+
- Zero abstraction leak
|
|
8
15
|
|
|
9
|
-
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
## 🚀 Key Features
|
|
13
|
-
|
|
14
|
-
- Fluent, chainable API
|
|
15
|
-
|
|
16
|
-
- Core independent of any Telegram library
|
|
17
|
-
|
|
18
|
-
- Easy-to-write adapters (Telegraf, node-telegram-bot-api, Aiogram...)
|
|
19
|
-
|
|
20
|
-
- Auto-wrap / control of buttons per row
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
---
|
|
16
|
+
---
|
|
25
17
|
|
|
26
18
|
## Installation
|
|
27
19
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
```bash
|
|
20
|
+
```bash
|
|
31
21
|
npm install telegram-inline-keyboard-builder
|
|
32
22
|
```
|
|
33
|
-
|
|
34
|
-
|
|
23
|
+
## importation
|
|
35
24
|
```js
|
|
36
|
-
import {
|
|
25
|
+
import { InlineKeyboardBuilder } from "telegram-inline-keyboard-builder";
|
|
37
26
|
```
|
|
38
27
|
|
|
39
|
-
|
|
28
|
+
## 🧠 Core Concept
|
|
40
29
|
|
|
41
|
-
|
|
30
|
+
Telegram inline keyboards follow **one universal schema**.
|
|
42
31
|
|
|
43
|
-
|
|
32
|
+
This builder:
|
|
44
33
|
|
|
45
|
-
|
|
34
|
+
* generates the keyboard **directly in Telegram format**
|
|
46
35
|
|
|
47
|
-
|
|
36
|
+
* lets you pass the result to **any Telegram library**
|
|
37
|
+
```js
|
|
38
|
+
{ reply_markup: { inline_keyboard: [...] } }
|
|
39
|
+
```
|
|
40
|
+
- **No adapters**.
|
|
41
|
+
- **No wrappers**.
|
|
42
|
+
- **No framework coupling**.
|
|
48
43
|
|
|
44
|
+
## 🔧 Public API
|
|
49
45
|
|
|
46
|
+
### Constructor
|
|
50
47
|
|
|
51
|
-
|
|
48
|
+
```js
|
|
49
|
+
new InlineKeyboardBuilder({ buttonsPerRow = 2, autoWrapMaxChars = 0 })
|
|
52
50
|
|
|
53
|
-
|
|
51
|
+
//Chainable Methods
|
|
54
52
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
53
|
+
.addCallbackButton(text, callback_data, hide = false)
|
|
54
|
+
.addUrlButton(text, url, hide = false)
|
|
55
|
+
.addPayButton(text, options = {})
|
|
56
|
+
.addCustomButton(buttonObject)
|
|
57
|
+
.addButtons(config)
|
|
58
|
+
.setButtonsPerRow(n)
|
|
59
|
+
.setAutoWrapMaxChars(n)
|
|
60
|
+
.newRow()
|
|
58
61
|
|
|
59
|
-
|
|
62
|
+
// build
|
|
63
|
+
.build()
|
|
60
64
|
|
|
61
|
-
|
|
62
|
-
new InlineKeyboardTelegraf({ buttonsPerRow = 2, autoWrapMaxChars = 0 })
|
|
63
|
-
new InlineKeyboardNodeTelegram({ ... })
|
|
65
|
+
const keyboard = builder.build();
|
|
64
66
|
|
|
65
|
-
|
|
67
|
+
// Always returns:
|
|
66
68
|
|
|
67
|
-
|
|
68
|
-
.addUrlButton(text, url, hide = false)
|
|
69
|
-
.addPayButton(text, options = {})
|
|
70
|
-
.addCustomButton(btnObj)
|
|
71
|
-
.addButtons(config) // array or { type, buttons: [...] }
|
|
72
|
-
.setButtonsPerRow(n)
|
|
73
|
-
.setAutoWrapMaxChars(n)
|
|
74
|
-
.newRow() // forces a new row
|
|
75
|
-
.build() // returns the keyboard formatted by the adapter
|
|
69
|
+
{ reply_markup: { inline_keyboard: [...] } }
|
|
76
70
|
```
|
|
77
|
-
|
|
71
|
+
Fully compliant with Telegram Bot API.
|
|
78
72
|
|
|
79
|
-
|
|
73
|
+
## Usage Example (Telegraf)
|
|
80
74
|
|
|
81
|
-
|
|
75
|
+
```js
|
|
76
|
+
import { Telegraf } from "telegraf";
|
|
82
77
|
|
|
78
|
+
import { InlineKeyboardBuilder } from "telegram-inline-keyboard-builder";
|
|
83
79
|
|
|
80
|
+
const bot = new Telegraf(process.env.BOT_TOKEN);
|
|
84
81
|
|
|
85
|
-
|
|
82
|
+
bot.start(ctx => {
|
|
83
|
+
const keyboard = new InlineKeyboardBuilder({ buttonsPerRow: 2, autoWrapMaxChars: 24 })
|
|
84
|
+
.addCallbackButton("✅ OK", "OK_ACTION")
|
|
85
|
+
.addUrlButton("🌍 Website", "https://example.com")
|
|
86
|
+
.newRow()
|
|
87
|
+
.addCallbackButton("❌ Cancel", "CANCEL_ACTION")
|
|
88
|
+
.build();
|
|
89
|
+
ctx.reply("Welcome 👋\nChoose an action:", keyboard); });
|
|
86
90
|
|
|
87
|
-
|
|
91
|
+
bot.launch();
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
## Usage Example (node-telegram-bot-api)
|
|
88
95
|
|
|
89
96
|
```js
|
|
90
|
-
import
|
|
91
|
-
import { InlineKeyboardTelegraf } from "telegram-inline-keyboard-builder";
|
|
97
|
+
import TelegramBot from "node-telegram-bot-api";
|
|
92
98
|
|
|
93
|
-
|
|
99
|
+
import { InlineKeyboardBuilder } from "telegram-inline-keyboard-builder";
|
|
94
100
|
|
|
95
|
-
bot
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
.build();
|
|
102
|
-
|
|
103
|
-
ctx.reply("Welcome 👋\nChoose an action:", keyboard);
|
|
104
|
-
});
|
|
101
|
+
const bot = new TelegramBot(TOKEN, { polling: true });
|
|
102
|
+
bot.onText(/\/start/, msg => {
|
|
103
|
+
const keyboard = new InlineKeyboardBuilder()
|
|
104
|
+
.addCallbackButton("OK", "OK")
|
|
105
|
+
.addUrlButton("Site", "https://example.com")
|
|
106
|
+
.build();
|
|
105
107
|
|
|
106
|
-
bot.
|
|
108
|
+
bot.sendMessage(msg.chat.id, "Hello", keyboard); });
|
|
107
109
|
```
|
|
108
110
|
|
|
109
|
-
##
|
|
111
|
+
## 💳 Payment Buttons
|
|
110
112
|
|
|
111
|
-
|
|
112
|
-
import TelegramBot from "node-telegram-bot-api";
|
|
113
|
-
import { InlineKeyboardNodeTelegram } from "telegram-inline-keyboard-builder";
|
|
114
|
-
|
|
115
|
-
const bot = new TelegramBot(TOKEN, { polling: true });
|
|
113
|
+
### ⚠️ Telegram limitation
|
|
116
114
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
.build();
|
|
115
|
+
> [!WARNING]
|
|
116
|
+
> Payment buttons must only be used with:
|
|
117
|
+
- sendInvoice
|
|
118
|
+
- replyWithInvoice
|
|
122
119
|
|
|
123
|
-
|
|
124
|
-
bot.sendMessage(msg.chat.id, "Hello", kb);
|
|
125
|
-
});
|
|
120
|
+
They must be hidden in normal messages.
|
|
126
121
|
|
|
122
|
+
```js
|
|
123
|
+
.addPayButton("Pay now");
|
|
127
124
|
```
|
|
128
|
-
---
|
|
129
125
|
|
|
130
|
-
|
|
126
|
+
Using a visible payment button outside invoices will cause Telegram API errors.
|
|
131
127
|
|
|
132
|
-
|
|
128
|
+
## 🧯 Common Errors
|
|
129
|
+
|
|
130
|
+
**Telegram API error**
|
|
131
|
+
|
|
132
|
+
Make sure the keyboard object is passed directly:
|
|
133
133
|
|
|
134
134
|
```js
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
135
|
+
const keyboard = new InlineKeyboardBuilder(1)
|
|
136
|
+
.addCallbackButton("Setting","show_setting")
|
|
137
|
+
.build()
|
|
138
|
+
// telegraf
|
|
139
|
+
ctx.reply("Text", keyboard);
|
|
139
140
|
|
|
140
|
-
//
|
|
141
|
-
|
|
141
|
+
// node telegram bot api
|
|
142
|
+
bot.sendMessage(chatId, "Text", keyboard);
|
|
142
143
|
|
|
143
|
-
|
|
144
|
+
// CORRECT ✅
|
|
144
145
|
|
|
145
|
-
|
|
146
|
-
createCallback(text, data) {
|
|
147
|
-
return { text, callback_data: data };
|
|
148
|
-
}
|
|
146
|
+
// OR if you want to include it in the options
|
|
149
147
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
148
|
+
const keyboard = new InlineKeyboardBuilder(1)
|
|
149
|
+
.addCallbackButton("Setting","show_setting")
|
|
150
|
+
.build()
|
|
153
151
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
152
|
+
// telegraf
|
|
153
|
+
ctx.reply("Text", {
|
|
154
|
+
reply_markup: keyboard.reply_makup, // inline keyboard
|
|
155
|
+
parse_mode: "HTML",
|
|
156
|
+
// ...
|
|
157
|
+
});
|
|
157
158
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
159
|
+
// node telegram bot api
|
|
160
|
+
bot.sendMessage(chatId, "Text", {
|
|
161
|
+
reply_markup: keyboard.reply_makup, // inline keyboard
|
|
162
|
+
parse_mode: "HTML",
|
|
163
|
+
// ...
|
|
164
|
+
);
|
|
162
165
|
```
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
-
|
|
168
|
-
|
|
169
|
-
|
|
166
|
+
## Migration to V2
|
|
167
|
+
|
|
168
|
+
- **V1**: The inline keyboard builder used **adapters** for each new API, resulting in code that was **unmaintainable** in case of **updates**.
|
|
169
|
+
|
|
170
|
+
- **V2**: Here we **simply construct an object valid for all types of APIs** without **adapting** it.
|
|
171
|
+
|
|
172
|
+
## 💜 Support This Project (Crypto)
|
|
173
|
+
|
|
174
|
+
This project is maintained in my free time.
|
|
175
|
+
If it helped you, consider supporting it with a crypto donation ❤️
|
|
176
|
+
It helps me maintain and improve the project.
|
|
177
|
+
|
|
178
|
+
You can send donations to the following addresses:
|
|
170
179
|
|
|
171
|
-
|
|
180
|
+
| Crypto | Address |
|
|
181
|
+
|--------|---------|
|
|
182
|
+
| **USDT (TRC20)** | `0x607c1430601989d43c9CD2eeD9E516663e0BdD1F` |
|
|
183
|
+
| **USDC (Polygon/ETH)** | `0x607c1430601989d43c9CD2eeD9E516663e0BdD1F` |
|
|
184
|
+
| **Ethereum (ETH)** | `0x607c1430601989d43c9CD2eeD9E516663e0BdD1F` |
|
|
185
|
+
| **Bitcoin (BTC)** | `bc1qmysepz6eerz2mqyx5dd0yy87c3gk6hccwla5x2` |
|
|
186
|
+
| **Tron (TRX)** | `TE9RiTaDpx7DGZzCMw7qds51nzszKiyeR8` |
|
|
187
|
+
| **TON** | `UQA1NPW4GqgIVa9R6lebN_0v64Q-Sz_nHrmK9LCk-FfdjVOH` |
|
|
172
188
|
|
|
173
|
-
|
|
189
|
+
### 🔹 Optional QR Codes for quick mobile donation
|
|
174
190
|
|
|
175
|
-
**
|
|
191
|
+
**USDT (TRC20)**
|
|
192
|
+
|
|
176
193
|
|
|
177
|
-
**
|
|
194
|
+
**USDC**
|
|
195
|
+
|
|
178
196
|
|
|
197
|
+
**Ethereum (ETH)**
|
|
198
|
+
|
|
179
199
|
|
|
180
|
-
|
|
200
|
+
**Bitcoin (BTC)**
|
|
201
|
+
|
|
181
202
|
|
|
182
|
-
|
|
203
|
+
**Tron (TRX)**
|
|
204
|
+
|
|
183
205
|
|
|
184
|
-
|
|
206
|
+
**TON**
|
|
207
|
+
|
|
185
208
|
|
|
209
|
+
## ✍️ Contribution
|
|
186
210
|
|
|
187
|
-
|
|
211
|
+
Contributions are welcome ❤️
|
|
212
|
+
Please open an issue before proposing major changes.
|