1 | <header>
|
2 |
|
3 | <div align="center">
|
4 | <img src="docs/assets/logo.svg" alt="logo" height="90" align="center">
|
5 | <h1 align="center">telegraf.js</h1>
|
6 |
|
7 | <p>Modern Telegram Bot API framework for Node.js</p>
|
8 |
|
9 | <a href="https://core.telegram.org/bots/api">
|
10 | <img src="https://img.shields.io/badge/Bot%20API-v6.5-f36caf.svg?style=flat-square" alt="Bot API Version" />
|
11 | </a>
|
12 | <a href="https://packagephobia.com/result?p=telegraf,node-telegram-bot-api">
|
13 | <img src="https://flat.badgen.net/packagephobia/install/telegraf" alt="install size" />
|
14 | </a>
|
15 | <a href="https://github.com/telegraf/telegraf">
|
16 | <img src="https://img.shields.io/github/languages/top/telegraf/telegraf?style=flat-square&logo=github" alt="GitHub top language" />
|
17 | </a>
|
18 | <a href="https://telegram.me/TelegrafJSChat">
|
19 | <img src="https://img.shields.io/badge/English%20chat-grey?style=flat-square&logo=telegram" alt="English chat" />
|
20 | </a>
|
21 | </div>
|
22 |
|
23 | </header>
|
24 |
|
25 | ## For 3.x users
|
26 |
|
27 | - [3.x docs](https://telegraf.js.org/v3)
|
28 | - [4.0 release notes](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)
|
29 |
|
30 | ## Introduction
|
31 |
|
32 | Bots are special [Telegram](https://telegram.org) accounts designed to handle messages automatically.
|
33 | Users can interact with bots by sending them command messages in private or group chats.
|
34 | These accounts serve as an interface for code running somewhere on your server.
|
35 |
|
36 | Telegraf is a library that makes it simple for you to develop your own Telegram bots using JavaScript or [TypeScript](https://www.typescriptlang.org/).
|
37 |
|
38 | ### Features
|
39 |
|
40 | - Full [Telegram Bot API 6.5](https://core.telegram.org/bots/api) support
|
41 | - [Excellent TypeScript typings](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)
|
42 | - [Lightweight](https://packagephobia.com/result?p=telegraf,node-telegram-bot-api)
|
43 | - [AWS **λ**](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html)
|
44 | / [Firebase](https://firebase.google.com/products/functions/)
|
45 | / [Glitch](https://glitch.com/edit/#!/dashing-light)
|
46 | / [Fly.io](https://fly.io/docs/languages-and-frameworks/node)
|
47 | / Whatever ready
|
48 | - `http/https/fastify/Connect.js/express.js` compatible webhooks
|
49 | - Extensible
|
50 |
|
51 | ### Example
|
52 |
|
53 | ```js
|
54 | const { Telegraf } = require('telegraf');
|
55 | const { message } = require('telegraf/filters');
|
56 |
|
57 | const bot = new Telegraf(process.env.BOT_TOKEN);
|
58 | bot.start((ctx) => ctx.reply('Welcome'));
|
59 | bot.help((ctx) => ctx.reply('Send me a sticker'));
|
60 | bot.on(message('sticker'), (ctx) => ctx.reply('👍'));
|
61 | bot.hears('hi', (ctx) => ctx.reply('Hey there'));
|
62 | bot.launch();
|
63 |
|
64 | // Enable graceful stop
|
65 | process.once('SIGINT', () => bot.stop('SIGINT'));
|
66 | process.once('SIGTERM', () => bot.stop('SIGTERM'));
|
67 | ```
|
68 |
|
69 | ```js
|
70 | const { Telegraf } = require('telegraf');
|
71 |
|
72 | const bot = new Telegraf(process.env.BOT_TOKEN);
|
73 | bot.command('oldschool', (ctx) => ctx.reply('Hello'));
|
74 | bot.command('hipster', Telegraf.reply('λ'));
|
75 | bot.launch();
|
76 |
|
77 | // Enable graceful stop
|
78 | process.once('SIGINT', () => bot.stop('SIGINT'));
|
79 | process.once('SIGTERM', () => bot.stop('SIGTERM'));
|
80 | ```
|
81 |
|
82 | For additional bot examples see the new [`docs repo`](https://github.com/feathers-studio/telegraf-docs/).
|
83 |
|
84 | ### Resources
|
85 |
|
86 | - [Getting started](#getting-started)
|
87 | - [API reference](https://telegraf.js.org/modules.html)
|
88 | - Telegram groups (sorted by number of members):
|
89 | * [English](https://t.me/TelegrafJSChat)
|
90 | * [Russian](https://t.me/telegrafjs_ru)
|
91 | * [Uzbek](https://t.me/botjs_uz)
|
92 | * [Ethiopian](https://t.me/telegraf_et)
|
93 | - [GitHub Discussions](https://github.com/telegraf/telegraf/discussions)
|
94 | - [Dependent repositories](https://libraries.io/npm/telegraf/dependent_repositories)
|
95 |
|
96 | ## Getting started
|
97 |
|
98 | ### Telegram token
|
99 |
|
100 | To use the [Telegram Bot API](https://core.telegram.org/bots/api),
|
101 | you first have to [get a bot account](https://core.telegram.org/bots)
|
102 | by [chatting with BotFather](https://core.telegram.org/bots#6-botfather).
|
103 |
|
104 | BotFather will give you a *token*, something like `123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ`.
|
105 |
|
106 | ### Installation
|
107 |
|
108 | ```shellscript
|
109 | $ npm install telegraf
|
110 | ```
|
111 | or
|
112 | ```shellscript
|
113 | $ yarn add telegraf
|
114 | ```
|
115 | or
|
116 | ```shellscript
|
117 | $ pnpm add telegraf
|
118 | ```
|
119 |
|
120 | ### `Telegraf` class
|
121 |
|
122 | [`Telegraf`] instance represents your bot. It's responsible for obtaining updates and passing them to your handlers.
|
123 |
|
124 | Start by [listening to commands](https://telegraf.js.org/classes/Telegraf-1.html#command) and [launching](https://telegraf.js.org/classes/Telegraf-1.html#launch) your bot.
|
125 |
|
126 | ### `Context` class
|
127 |
|
128 | `ctx` you can see in every example is a [`Context`] instance.
|
129 | [`Telegraf`] creates one for each incoming update and passes it to your middleware.
|
130 | It contains the `update`, `botInfo`, and `telegram` for making arbitrary Bot API requests,
|
131 | as well as shorthand methods and getters.
|
132 |
|
133 | This is probably the class you'll be using the most.
|
134 |
|
135 |
|
136 |
|
137 | TODO: Verify and update list
|
138 | Here is a list of
|
139 |
|
140 | #### Known middleware
|
141 |
|
142 | - [Internationalization](https://github.com/telegraf/telegraf-i18n)—simplifies selecting the right translation to use when responding to a user.
|
143 | - [Redis powered session](https://github.com/telegraf/telegraf-session-redis)—store session data using Redis.
|
144 | - [Local powered session (via lowdb)](https://github.com/RealSpeaker/telegraf-session-local)—store session data in a local file.
|
145 | - [Rate-limiting](https://github.com/telegraf/telegraf-ratelimit)—apply rate limitting to chats or users.
|
146 | - [Bottleneck powered throttling](https://github.com/KnightNiwrem/telegraf-throttler)—apply throttling to both incoming updates and outgoing API calls.
|
147 | - [Menus via inline keyboards](https://github.com/EdJoPaTo/telegraf-inline-menu)—simplify creating interfaces based on menus.
|
148 | - [Stateless Questions](https://github.com/EdJoPaTo/telegraf-stateless-question)—create stateless questions to Telegram users working in privacy mode.
|
149 | - [Natural language processing via wit.ai](https://github.com/telegraf/telegraf-wit)
|
150 | - [Natural language processing via recast.ai](https://github.com/telegraf/telegraf-recast)
|
151 | - [Multivariate and A/B testing](https://github.com/telegraf/telegraf-experiments)—add experiments to see how different versions of a feature are used.
|
152 | - [Powerfull bot stats via Mixpanel](https://github.com/telegraf/telegraf-mixpanel)
|
153 | - [statsd integration](https://github.com/telegraf/telegraf-statsd)
|
154 | - [and more...](https://www.npmjs.com/search?q=telegraf-)
|
155 | -->
|
156 |
|
157 | #### Shorthand methods
|
158 |
|
159 | ```js
|
160 | import { Telegraf } from 'telegraf';
|
161 | import { message } from 'telegraf/filters';
|
162 |
|
163 | const bot = new Telegraf(process.env.BOT_TOKEN);
|
164 |
|
165 | bot.command('quit', async (ctx) => {
|
166 | // Explicit usage
|
167 | await ctx.telegram.leaveChat(ctx.message.chat.id);
|
168 |
|
169 | // Using context shortcut
|
170 | await ctx.leaveChat();
|
171 | });
|
172 |
|
173 | bot.on(message('text'), async (ctx) => {
|
174 | // Explicit usage
|
175 | await ctx.telegram.sendMessage(ctx.message.chat.id, `Hello ${ctx.state.role}`);
|
176 |
|
177 | // Using context shortcut
|
178 | await ctx.reply(`Hello ${ctx.state.role}`);
|
179 | });
|
180 |
|
181 | bot.on('callback_query', async (ctx) => {
|
182 | // Explicit usage
|
183 | await ctx.telegram.answerCbQuery(ctx.callbackQuery.id);
|
184 |
|
185 | // Using context shortcut
|
186 | await ctx.answerCbQuery();
|
187 | });
|
188 |
|
189 | bot.on('inline_query', async (ctx) => {
|
190 | const result = [];
|
191 | // Explicit usage
|
192 | await ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result);
|
193 |
|
194 | // Using context shortcut
|
195 | await ctx.answerInlineQuery(result);
|
196 | });
|
197 |
|
198 | bot.launch();
|
199 |
|
200 | // Enable graceful stop
|
201 | process.once('SIGINT', () => bot.stop('SIGINT'));
|
202 | process.once('SIGTERM', () => bot.stop('SIGTERM'));
|
203 | ```
|
204 |
|
205 | ## Production
|
206 |
|
207 | ### Webhooks
|
208 |
|
209 | ```TS
|
210 | import { Telegraf } from "telegraf";
|
211 | import { message } from 'telegraf/filters';
|
212 |
|
213 | const bot = new Telegraf(token);
|
214 |
|
215 | bot.on(message("text"), ctx => ctx.reply("Hello"));
|
216 |
|
217 | // Start webhook via launch method (preferred)
|
218 | bot.launch({
|
219 | webhook: {
|
220 | // Public domain for webhook; e.g.: example.com
|
221 | domain: webhookDomain,
|
222 |
|
223 | // Port to listen on; e.g.: 8080
|
224 | port: port,
|
225 |
|
226 | // Optional path to listen for.
|
227 | // `bot.secretPathComponent()` will be used by default
|
228 | hookPath: webhookPath,
|
229 |
|
230 | // Optional secret to be sent back in a header for security.
|
231 | // e.g.: `crypto.randomBytes(64).toString("hex")`
|
232 | secretToken: randomAlphaNumericString,
|
233 | },
|
234 | });
|
235 | ```
|
236 |
|
237 | Use `createWebhook()` if you want to attach Telegraf to an existing http server.
|
238 |
|
239 |
|
240 |
|
241 | ```TS
|
242 | import { createServer } from "http";
|
243 |
|
244 | createServer(await bot.createWebhook({ domain: "example.com" })).listen(3000);
|
245 | ```
|
246 |
|
247 | ```TS
|
248 | import { createServer } from "https";
|
249 |
|
250 | createServer(tlsOptions, await bot.createWebhook({ domain: "example.com" })).listen(8443);
|
251 | ```
|
252 |
|
253 | - [AWS Lambda example integration](https://github.com/feathers-studio/telegraf-docs/tree/master/examples/functions/aws-lambda)
|
254 | - [Google Cloud Functions example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/functions/google-cloud-function.ts)
|
255 | - [`express` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/express.ts)
|
256 | - [`fastify` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/fastify.ts)
|
257 | - [`koa` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/koa.ts)
|
258 | - [NestJS framework integration module](https://github.com/bukhalo/nestjs-telegraf)
|
259 | - [Cloudflare Workers integration module](https://github.com/Tsuk1ko/cfworker-middware-telegraf)
|
260 | - Use [`bot.handleUpdate`](https://telegraf.js.org/classes/Telegraf-1.html#handleupdate) to write new integrations
|
261 |
|
262 | ### Error handling
|
263 |
|
264 | If middleware throws an error or times out, Telegraf calls `bot.handleError`. If it rethrows, update source closes, and then the error is printed to console and process terminates. If it does not rethrow, the error is swallowed.
|
265 |
|
266 | Default `bot.handleError` always rethrows. You can overwrite it using `bot.catch` if you need to.
|
267 |
|
268 | ⚠️ Swallowing unknown errors might leave the process in invalid state!
|
269 |
|
270 | ℹ️ In production, `systemd` or [`pm2`](https://www.npmjs.com/package/pm2) can restart your bot if it exits for any reason.
|
271 |
|
272 | ## Advanced topics
|
273 |
|
274 | ### Working with files
|
275 |
|
276 | Supported file sources:
|
277 |
|
278 | - `Existing file_id`
|
279 | - `File path`
|
280 | - `Url`
|
281 | - `Buffer`
|
282 | - `ReadStream`
|
283 |
|
284 | Also, you can provide an optional name of a file as `filename` when you send the file.
|
285 |
|
286 |
|
287 |
|
288 | ```js
|
289 | bot.on('message', async (ctx) => {
|
290 | // resend existing file by file_id
|
291 | await ctx.replyWithSticker('123123jkbhj6b');
|
292 |
|
293 | // send file
|
294 | await ctx.replyWithVideo(Input.fromLocalFile('/path/to/video.mp4'));
|
295 |
|
296 | // send stream
|
297 | await ctx.replyWithVideo(Input.fromReadableStream(fs.createReadStream('/path/to/video.mp4')));
|
298 |
|
299 | // send buffer
|
300 | await ctx.replyWithVoice(Input.fromBuffer(Buffer.alloc()));
|
301 |
|
302 | // send url via Telegram server
|
303 | await ctx.replyWithPhoto(Input.fromURL('https://picsum.photos/200/300/'));
|
304 |
|
305 | // pipe url content
|
306 | await ctx.replyWithPhoto(Input.fromURLStream('https://picsum.photos/200/300/?random', 'kitten.jpg'));
|
307 | })
|
308 | ```
|
309 |
|
310 | ### Middleware
|
311 |
|
312 | In addition to `ctx: Context`, each middleware receives `next: () => Promise<void>`.
|
313 |
|
314 | As in Koa and some other middleware-based libraries,
|
315 | `await next()` will call next middleware and wait for it to finish:
|
316 |
|
317 | ```TS
|
318 | import { Telegraf } from 'telegraf';
|
319 | import { message } from 'telegraf/filters';
|
320 |
|
321 | const bot = new Telegraf(process.env.BOT_TOKEN);
|
322 |
|
323 | bot.use(async (ctx, next) => {
|
324 | console.time(`Processing update ${ctx.update.update_id}`);
|
325 | await next() // runs next middleware
|
326 | // runs after next middleware finishes
|
327 | console.timeEnd(`Processing update ${ctx.update.update_id}`);
|
328 | })
|
329 |
|
330 | bot.on(message('text'), (ctx) => ctx.reply('Hello World'));
|
331 | bot.launch();
|
332 |
|
333 | // Enable graceful stop
|
334 | process.once('SIGINT', () => bot.stop('SIGINT'));
|
335 | process.once('SIGTERM', () => bot.stop('SIGTERM'));
|
336 | ```
|
337 |
|
338 | With this simple ability, you can:
|
339 | - extract information from updates and then `await next()` to avoid disrupting other middleware,
|
340 | - like [`Composer`] and [`Router`], `await next()` for updates you don't wish to handle,
|
341 | - like [`session`] and [`Scenes`], [extend the context](#extending-context) by mutating `ctx` before `await next()`,
|
342 | - [intercept API calls](https://github.com/telegraf/telegraf/discussions/1267#discussioncomment-254525),
|
343 | - reuse [other people's code](https://www.npmjs.com/search?q=telegraf-),
|
344 | - do whatever **you** come up with!
|
345 |
|
346 | [`Telegraf`]: https://telegraf.js.org/classes/Telegraf-1.html
|
347 | [`Composer`]: https://telegraf.js.org/classes/Composer.html
|
348 | [`Context`]: https://telegraf.js.org/classes/Context.html
|
349 | [`Router`]: https://telegraf.js.org/classes/Router.html
|
350 | [`session`]: https://telegraf.js.org/modules.html#session
|
351 | [`Scenes`]: https://telegraf.js.org/modules/Scenes.html
|
352 |
|
353 | ### Usage with TypeScript
|
354 |
|
355 | Telegraf is written in TypeScript and therefore ships with declaration files for the entire library.
|
356 | Moreover, it includes types for the complete Telegram API via the [`typegram`](https://github.com/KnorpelSenf/typegram) package.
|
357 | While most types of Telegraf's API surface are self-explanatory, there's some notable things to keep in mind.
|
358 |
|
359 | #### Extending `Context`
|
360 |
|
361 | The exact shape of `ctx` can vary based on the installed middleware.
|
362 | Some custom middleware might register properties on the context object that Telegraf is not aware of.
|
363 | Consequently, you can change the type of `ctx` to fit your needs in order for you to have proper TypeScript types for your data.
|
364 | This is done through Generics:
|
365 |
|
366 | ```ts
|
367 | import { Context, Telegraf } from 'telegraf';
|
368 |
|
369 | // Define your own context type
|
370 | interface MyContext extends Context {
|
371 | myProp?: string
|
372 | myOtherProp?: number
|
373 | }
|
374 |
|
375 | // Create your bot and tell it about your context type
|
376 | const bot = new Telegraf<MyContext>('SECRET TOKEN');
|
377 |
|
378 | // Register middleware and launch your bot as usual
|
379 | bot.use((ctx, next) => {
|
380 | // Yay, `myProp` is now available here as `string | undefined`!
|
381 | ctx.myProp = ctx.chat?.first_name?.toUpperCase();
|
382 | return next();
|
383 | });
|
384 | // ...
|
385 | ```
|