UNPKG

13.8 kBMarkdownView Raw
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
32Bots are special [Telegram](https://telegram.org) accounts designed to handle messages automatically.
33Users can interact with bots by sending them command messages in private or group chats.
34These accounts serve as an interface for code running somewhere on your server.
35
36Telegraf 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
54const { Telegraf } = require('telegraf');
55const { message } = require('telegraf/filters');
56
57const bot = new Telegraf(process.env.BOT_TOKEN);
58bot.start((ctx) => ctx.reply('Welcome'));
59bot.help((ctx) => ctx.reply('Send me a sticker'));
60bot.on(message('sticker'), (ctx) => ctx.reply('👍'));
61bot.hears('hi', (ctx) => ctx.reply('Hey there'));
62bot.launch();
63
64// Enable graceful stop
65process.once('SIGINT', () => bot.stop('SIGINT'));
66process.once('SIGTERM', () => bot.stop('SIGTERM'));
67```
68
69```js
70const { Telegraf } = require('telegraf');
71
72const bot = new Telegraf(process.env.BOT_TOKEN);
73bot.command('oldschool', (ctx) => ctx.reply('Hello'));
74bot.command('hipster', Telegraf.reply('λ'));
75bot.launch();
76
77// Enable graceful stop
78process.once('SIGINT', () => bot.stop('SIGINT'));
79process.once('SIGTERM', () => bot.stop('SIGTERM'));
80```
81
82For 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
100To use the [Telegram Bot API](https://core.telegram.org/bots/api),
101you first have to [get a bot account](https://core.telegram.org/bots)
102by [chatting with BotFather](https://core.telegram.org/bots#6-botfather).
103
104BotFather will give you a *token*, something like `123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ`.
105
106### Installation
107
108```shellscript
109$ npm install telegraf
110```
111or
112```shellscript
113$ yarn add telegraf
114```
115or
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
124Start 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.
130It contains the `update`, `botInfo`, and `telegram` for making arbitrary Bot API requests,
131as well as shorthand methods and getters.
132
133This is probably the class you'll be using the most.
134
135
136<!--
137TODO: Verify and update list
138Here 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
160import { Telegraf } from 'telegraf';
161import { message } from 'telegraf/filters';
162
163const bot = new Telegraf(process.env.BOT_TOKEN);
164
165bot.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
173bot.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
181bot.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
189bot.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
198bot.launch();
199
200// Enable graceful stop
201process.once('SIGINT', () => bot.stop('SIGINT'));
202process.once('SIGTERM', () => bot.stop('SIGTERM'));
203```
204
205## Production
206
207### Webhooks
208
209```TS
210import { Telegraf } from "telegraf";
211import { message } from 'telegraf/filters';
212
213const bot = new Telegraf(token);
214
215bot.on(message("text"), ctx => ctx.reply("Hello"));
216
217// Start webhook via launch method (preferred)
218bot.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
237Use `createWebhook()` if you want to attach Telegraf to an existing http server.
238
239<!-- global bot, tlsOptions -->
240
241```TS
242import { createServer } from "http";
243
244createServer(await bot.createWebhook({ domain: "example.com" })).listen(3000);
245```
246
247```TS
248import { createServer } from "https";
249
250createServer(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
264If 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
266Default `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
276Supported file sources:
277
278- `Existing file_id`
279- `File path`
280- `Url`
281- `Buffer`
282- `ReadStream`
283
284Also, you can provide an optional name of a file as `filename` when you send the file.
285
286<!-- global bot, fs -->
287
288```js
289bot.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
312In addition to `ctx: Context`, each middleware receives `next: () => Promise<void>`.
313
314As in Koa and some other middleware-based libraries,
315`await next()` will call next middleware and wait for it to finish:
316
317```TS
318import { Telegraf } from 'telegraf';
319import { message } from 'telegraf/filters';
320
321const bot = new Telegraf(process.env.BOT_TOKEN);
322
323bot.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
330bot.on(message('text'), (ctx) => ctx.reply('Hello World'));
331bot.launch();
332
333// Enable graceful stop
334process.once('SIGINT', () => bot.stop('SIGINT'));
335process.once('SIGTERM', () => bot.stop('SIGTERM'));
336```
337
338With 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
355Telegraf is written in TypeScript and therefore ships with declaration files for the entire library.
356Moreover, it includes types for the complete Telegram API via the [`typegram`](https://github.com/KnorpelSenf/typegram) package.
357While most types of Telegraf's API surface are self-explanatory, there's some notable things to keep in mind.
358
359#### Extending `Context`
360
361The exact shape of `ctx` can vary based on the installed middleware.
362Some custom middleware might register properties on the context object that Telegraf is not aware of.
363Consequently, you can change the type of `ctx` to fit your needs in order for you to have proper TypeScript types for your data.
364This is done through Generics:
365
366```ts
367import { Context, Telegraf } from 'telegraf';
368
369// Define your own context type
370interface MyContext extends Context {
371 myProp?: string
372 myOtherProp?: number
373}
374
375// Create your bot and tell it about your context type
376const bot = new Telegraf<MyContext>('SECRET TOKEN');
377
378// Register middleware and launch your bot as usual
379bot.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```