{"id":13454421,"url":"https://github.com/telegraf/telegraf","last_synced_at":"2025-05-12T03:35:43.986Z","repository":{"id":37431768,"uuid":"56398352","full_name":"telegraf/telegraf","owner":"telegraf","description":"Modern Telegram Bot Framework for Node.js","archived":false,"fork":false,"pushed_at":"2025-01-11T06:02:13.000Z","size":6530,"stargazers_count":8694,"open_issues_count":72,"forks_count":949,"subscribers_count":113,"default_branch":"v4","last_synced_at":"2025-05-11T00:28:25.901Z","etag":null,"topics":["bot","bot-api","bot-framework","hacktoberfest","middleware","telegraf","telegram","telegram-bot","telegram-bot-api","telegram-bots"],"latest_commit_sha":null,"homepage":"https://telegraf.js.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telegraf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["dotcypress"],"open_collective":"telegraf"}},"created_at":"2016-04-16T18:05:48.000Z","updated_at":"2025-05-10T16:39:55.000Z","dependencies_parsed_at":"2023-09-22T01:36:24.128Z","dependency_job_id":"666e6580-e71c-44db-aff7-693178f0fcb8","html_url":"https://github.com/telegraf/telegraf","commit_stats":{"total_commits":1301,"total_committers":157,"mean_commits":8.286624203821656,"dds":0.5488086087624904,"last_synced_commit":"48a475d034ede5e01070a7e2b6b15dc48c3d3f9b"},"previous_names":[],"tags_count":205,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegraf%2Ftelegraf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegraf%2Ftelegraf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegraf%2Ftelegraf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telegraf%2Ftelegraf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telegraf","download_url":"https://codeload.github.com/telegraf/telegraf/tar.gz/refs/heads/v4","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655919,"owners_count":21943072,"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":["bot","bot-api","bot-framework","hacktoberfest","middleware","telegraf","telegram","telegram-bot","telegram-bot-api","telegram-bots"],"created_at":"2024-07-31T08:00:53.926Z","updated_at":"2025-05-12T03:35:43.947Z","avatar_url":"https://github.com/telegraf.png","language":"TypeScript","readme":"\u003cheader\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/assets/logo.svg\" alt=\"logo\" height=\"90\" align=\"center\"\u003e\n\u003ch1 align=\"center\"\u003etelegraf.js\u003c/h1\u003e\n\n\u003cp\u003eModern Telegram Bot API framework for Node.js\u003c/p\u003e\n\n\u003ca href=\"https://core.telegram.org/bots/api\"\u003e\n\t\u003cimg src=\"https://img.shields.io/badge/Bot%20API-v7.1-f36caf.svg?style=flat-square\" alt=\"Bot API Version\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://packagephobia.com/result?p=telegraf,node-telegram-bot-api\"\u003e\n\t\u003cimg src=\"https://flat.badgen.net/packagephobia/install/telegraf\" alt=\"install size\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/telegraf/telegraf\"\u003e\n\t\u003cimg src=\"https://img.shields.io/github/languages/top/telegraf/telegraf?style=flat-square\u0026logo=github\" alt=\"GitHub top language\" /\u003e\n\u003c/a\u003e\n\u003ca href=\"https://telegram.me/TelegrafJSChat\"\u003e\n\t\u003cimg src=\"https://img.shields.io/badge/English%20chat-grey?style=flat-square\u0026logo=telegram\" alt=\"English chat\" /\u003e\n\u003c/a\u003e\n\u003c/div\u003e\n\n\u003c/header\u003e\n\n## For 3.x users\n\n- [3.x docs](https://telegraf.js.org/v3)\n- [4.0 release notes](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)\n\n## Introduction\n\nBots are special [Telegram](https://telegram.org) accounts designed to handle messages automatically.\nUsers can interact with bots by sending them command messages in private or group chats.\nThese accounts serve as an interface for code running somewhere on your server.\n\nTelegraf is a library that makes it simple for you to develop your own Telegram bots using JavaScript or [TypeScript](https://www.typescriptlang.org/).\n\n### Features\n\n- Full [Telegram Bot API 7.1](https://core.telegram.org/bots/api) support\n- [Excellent TypeScript typings](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)\n- [Lightweight](https://packagephobia.com/result?p=telegraf,node-telegram-bot-api)\n- [AWS **λ**](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html)\n  / [Firebase](https://firebase.google.com/products/functions/)\n  / [Glitch](https://glitch.com/edit/#!/dashing-light)\n  / [Fly.io](https://fly.io/docs/languages-and-frameworks/node)\n  / Whatever ready\n- `http/https/fastify/Connect.js/express.js` compatible webhooks\n- Extensible\n\n### Example\n\n```js\nconst { Telegraf } = require('telegraf')\nconst { message } = require('telegraf/filters')\n\nconst bot = new Telegraf(process.env.BOT_TOKEN)\nbot.start((ctx) =\u003e ctx.reply('Welcome'))\nbot.help((ctx) =\u003e ctx.reply('Send me a sticker'))\nbot.on(message('sticker'), (ctx) =\u003e ctx.reply('👍'))\nbot.hears('hi', (ctx) =\u003e ctx.reply('Hey there'))\nbot.launch()\n\n// Enable graceful stop\nprocess.once('SIGINT', () =\u003e bot.stop('SIGINT'))\nprocess.once('SIGTERM', () =\u003e bot.stop('SIGTERM'))\n```\n\n```js\nconst { Telegraf } = require('telegraf')\n\nconst bot = new Telegraf(process.env.BOT_TOKEN)\nbot.command('oldschool', (ctx) =\u003e ctx.reply('Hello'))\nbot.command('hipster', Telegraf.reply('λ'))\nbot.launch()\n\n// Enable graceful stop\nprocess.once('SIGINT', () =\u003e bot.stop('SIGINT'))\nprocess.once('SIGTERM', () =\u003e bot.stop('SIGTERM'))\n```\n\nFor additional bot examples see the new [`docs repo`](https://github.com/feathers-studio/telegraf-docs/).\n\n### Resources\n\n- [Getting started](#getting-started)\n- [API reference](https://telegraf.js.org/modules.html)\n- Telegram groups (sorted by number of members):\n  - [English](https://t.me/TelegrafJSChat)\n  - [Russian](https://t.me/telegrafjs_ru)\n  - [Uzbek](https://t.me/botjs_uz)\n  - [Ethiopian](https://t.me/telegraf_et)\n- [GitHub Discussions](https://github.com/telegraf/telegraf/discussions)\n- [Dependent repositories](https://libraries.io/npm/telegraf/dependent_repositories)\n\n## Getting started\n\n### Telegram token\n\nTo use the [Telegram Bot API](https://core.telegram.org/bots/api),\nyou first have to [get a bot account](https://core.telegram.org/bots)\nby [chatting with BotFather](https://core.telegram.org/bots#6-botfather).\n\nBotFather will give you a _token_, something like `123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ`.\n\n### Installation\n\n```shellscript\n$ npm install telegraf\n```\n\nor\n\n```shellscript\n$ yarn add telegraf\n```\n\nor\n\n```shellscript\n$ pnpm add telegraf\n```\n\n### `Telegraf` class\n\n[`Telegraf`] instance represents your bot. It's responsible for obtaining updates and passing them to your handlers.\n\nStart 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.\n\n### `Context` class\n\n`ctx` you can see in every example is a [`Context`] instance.\n[`Telegraf`] creates one for each incoming update and passes it to your middleware.\nIt contains the `update`, `botInfo`, and `telegram` for making arbitrary Bot API requests,\nas well as shorthand methods and getters.\n\nThis is probably the class you'll be using the most.\n\n\u003c!--\nTODO: Verify and update list\nHere is a list of\n\n#### Known middleware\n\n- [Internationalization](https://github.com/telegraf/telegraf-i18n)—simplifies selecting the right translation to use when responding to a user.\n- [Redis powered session](https://github.com/telegraf/telegraf-session-redis)—store session data using Redis.\n- [Local powered session (via lowdb)](https://github.com/RealSpeaker/telegraf-session-local)—store session data in a local file.\n- [Rate-limiting](https://github.com/telegraf/telegraf-ratelimit)—apply rate limitting to chats or users.\n- [Bottleneck powered throttling](https://github.com/KnightNiwrem/telegraf-throttler)—apply throttling to both incoming updates and outgoing API calls.\n- [Menus via inline keyboards](https://github.com/EdJoPaTo/telegraf-inline-menu)—simplify creating interfaces based on menus.\n- [Stateless Questions](https://github.com/EdJoPaTo/telegraf-stateless-question)—create stateless questions to Telegram users working in privacy mode.\n- [Natural language processing via wit.ai](https://github.com/telegraf/telegraf-wit)\n- [Natural language processing via recast.ai](https://github.com/telegraf/telegraf-recast)\n- [Multivariate and A/B testing](https://github.com/telegraf/telegraf-experiments)—add experiments to see how different versions of a feature are used.\n- [Powerfull bot stats via Mixpanel](https://github.com/telegraf/telegraf-mixpanel)\n- [statsd integration](https://github.com/telegraf/telegraf-statsd)\n- [and more...](https://www.npmjs.com/search?q=telegraf-)\n--\u003e\n\n#### Shorthand methods\n\n```js\nimport { Telegraf } from 'telegraf'\nimport { message } from 'telegraf/filters'\n\nconst bot = new Telegraf(process.env.BOT_TOKEN)\n\nbot.command('quit', async (ctx) =\u003e {\n  // Explicit usage\n  await ctx.telegram.leaveChat(ctx.message.chat.id)\n\n  // Using context shortcut\n  await ctx.leaveChat()\n})\n\nbot.on(message('text'), async (ctx) =\u003e {\n  // Explicit usage\n  await ctx.telegram.sendMessage(ctx.message.chat.id, `Hello ${ctx.state.role}`)\n\n  // Using context shortcut\n  await ctx.reply(`Hello ${ctx.state.role}`)\n})\n\nbot.on('callback_query', async (ctx) =\u003e {\n  // Explicit usage\n  await ctx.telegram.answerCbQuery(ctx.callbackQuery.id)\n\n  // Using context shortcut\n  await ctx.answerCbQuery()\n})\n\nbot.on('inline_query', async (ctx) =\u003e {\n  const result = []\n  // Explicit usage\n  await ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result)\n\n  // Using context shortcut\n  await ctx.answerInlineQuery(result)\n})\n\nbot.launch()\n\n// Enable graceful stop\nprocess.once('SIGINT', () =\u003e bot.stop('SIGINT'))\nprocess.once('SIGTERM', () =\u003e bot.stop('SIGTERM'))\n```\n\n## Production\n\n### Webhooks\n\n```TS\nimport { Telegraf } from \"telegraf\";\nimport { message } from 'telegraf/filters';\n\nconst bot = new Telegraf(token);\n\nbot.on(message(\"text\"), ctx =\u003e ctx.reply(\"Hello\"));\n\n// Start webhook via launch method (preferred)\nbot.launch({\n  webhook: {\n    // Public domain for webhook; e.g.: example.com\n    domain: webhookDomain,\n\n    // Port to listen on; e.g.: 8080\n    port: port,\n\n    // Optional path to listen for.\n    // `bot.secretPathComponent()` will be used by default\n    path: webhookPath,\n\n    // Optional secret to be sent back in a header for security.\n    // e.g.: `crypto.randomBytes(64).toString(\"hex\")`\n    secretToken: randomAlphaNumericString,\n  },\n});\n```\n\nUse `createWebhook()` if you want to attach Telegraf to an existing http server.\n\n\u003c!-- global bot, tlsOptions --\u003e\n\n```TS\nimport { createServer } from \"http\";\n\ncreateServer(await bot.createWebhook({ domain: \"example.com\" })).listen(3000);\n```\n\n```TS\nimport { createServer } from \"https\";\n\ncreateServer(tlsOptions, await bot.createWebhook({ domain: \"example.com\" })).listen(8443);\n```\n\n- [AWS Lambda example integration](https://github.com/feathers-studio/telegraf-docs/tree/master/examples/functions/aws-lambda)\n- [Google Cloud Functions example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/functions/google-cloud-function.ts)\n- [`express` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/express.ts)\n- [`fastify` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/fastify.ts)\n- [`koa` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/koa.ts)\n- [NestJS framework integration module](https://github.com/bukhalo/nestjs-telegraf)\n- [Cloudflare Workers integration module](https://github.com/Tsuk1ko/cfworker-middware-telegraf)\n- Use [`bot.handleUpdate`](https://telegraf.js.org/classes/Telegraf-1.html#handleupdate) to write new integrations\n\n### Error handling\n\nIf 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.\n\nDefault `bot.handleError` always rethrows. You can overwrite it using `bot.catch` if you need to.\n\n⚠️ Swallowing unknown errors might leave the process in invalid state!\n\nℹ️ In production, `systemd` or [`pm2`](https://www.npmjs.com/package/pm2) can restart your bot if it exits for any reason.\n\n## Advanced topics\n\n### Working with files\n\nSupported file sources:\n\n- `Existing file_id`\n- `File path`\n- `Url`\n- `Buffer`\n- `ReadStream`\n\nAlso, you can provide an optional name of a file as `filename` when you send the file.\n\n\u003c!-- global bot, fs --\u003e\n\n```js\nbot.on('message', async (ctx) =\u003e {\n  // resend existing file by file_id\n  await ctx.replyWithSticker('123123jkbhj6b')\n\n  // send file\n  await ctx.replyWithVideo(Input.fromLocalFile('/path/to/video.mp4'))\n\n  // send stream\n  await ctx.replyWithVideo(\n    Input.fromReadableStream(fs.createReadStream('/path/to/video.mp4'))\n  )\n\n  // send buffer\n  await ctx.replyWithVoice(Input.fromBuffer(Buffer.alloc()))\n\n  // send url via Telegram server\n  await ctx.replyWithPhoto(Input.fromURL('https://picsum.photos/200/300/'))\n\n  // pipe url content\n  await ctx.replyWithPhoto(\n    Input.fromURLStream('https://picsum.photos/200/300/?random', 'kitten.jpg')\n  )\n})\n```\n\n### Middleware\n\nIn addition to `ctx: Context`, each middleware receives `next: () =\u003e Promise\u003cvoid\u003e`.\n\nAs in Koa and some other middleware-based libraries,\n`await next()` will call next middleware and wait for it to finish:\n\n```TS\nimport { Telegraf } from 'telegraf';\nimport { message } from 'telegraf/filters';\n\nconst bot = new Telegraf(process.env.BOT_TOKEN);\n\nbot.use(async (ctx, next) =\u003e {\n  console.time(`Processing update ${ctx.update.update_id}`);\n  await next() // runs next middleware\n  // runs after next middleware finishes\n  console.timeEnd(`Processing update ${ctx.update.update_id}`);\n})\n\nbot.on(message('text'), (ctx) =\u003e ctx.reply('Hello World'));\nbot.launch();\n\n// Enable graceful stop\nprocess.once('SIGINT', () =\u003e bot.stop('SIGINT'));\nprocess.once('SIGTERM', () =\u003e bot.stop('SIGTERM'));\n```\n\nWith this simple ability, you can:\n\n- extract information from updates and then `await next()` to avoid disrupting other middleware,\n- like [`Composer`] and [`Router`], `await next()` for updates you don't wish to handle,\n- like [`session`] and [`Scenes`], [extend the context](#extending-context) by mutating `ctx` before `await next()`,\n- [intercept API calls](https://github.com/telegraf/telegraf/discussions/1267#discussioncomment-254525),\n- reuse [other people's code](https://www.npmjs.com/search?q=telegraf-),\n- do whatever **you** come up with!\n\n[`Telegraf`]: https://telegraf.js.org/classes/Telegraf-1.html\n[`Composer`]: https://telegraf.js.org/classes/Composer.html\n[`Context`]: https://telegraf.js.org/classes/Context.html\n[`Router`]: https://telegraf.js.org/classes/Router.html\n[`session`]: https://telegraf.js.org/modules.html#session\n[`Scenes`]: https://telegraf.js.org/modules/Scenes.html\n\n### Usage with TypeScript\n\nTelegraf is written in TypeScript and therefore ships with declaration files for the entire library.\nMoreover, it includes types for the complete Telegram API via the [`typegram`](https://github.com/KnorpelSenf/typegram) package.\nWhile most types of Telegraf's API surface are self-explanatory, there's some notable things to keep in mind.\n\n#### Extending `Context`\n\nThe exact shape of `ctx` can vary based on the installed middleware.\nSome custom middleware might register properties on the context object that Telegraf is not aware of.\nConsequently, you can change the type of `ctx` to fit your needs in order for you to have proper TypeScript types for your data.\nThis is done through Generics:\n\n```ts\nimport { Context, Telegraf } from 'telegraf'\n\n// Define your own context type\ninterface MyContext extends Context {\n  myProp?: string\n  myOtherProp?: number\n}\n\n// Create your bot and tell it about your context type\nconst bot = new Telegraf\u003cMyContext\u003e('SECRET TOKEN')\n\n// Register middleware and launch your bot as usual\nbot.use((ctx, next) =\u003e {\n  // Yay, `myProp` is now available here as `string | undefined`!\n  ctx.myProp = ctx.chat?.first_name?.toUpperCase()\n  return next()\n})\n// ...\n```\n","funding_links":["https://github.com/sponsors/dotcypress","https://opencollective.com/telegraf"],"categories":["TypeScript","JavaScript","后端开发框架及项目","Telegram Libraries","Bots","Libraries","一般机器人（bots）"],"sub_categories":["管理面板","Node","Bot Libs","Telegram","机器人类库","Node.js"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelegraf%2Ftelegraf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelegraf%2Ftelegraf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelegraf%2Ftelegraf/lists"}