{"id":15821171,"url":"https://github.com/eomm/fastify-telegram","last_synced_at":"2025-09-17T16:32:41.989Z","repository":{"id":199117727,"uuid":"702131861","full_name":"Eomm/fastify-telegram","owner":"Eomm","description":"Create and manage a Telegram bot, easily","archived":false,"fork":false,"pushed_at":"2024-03-04T02:31:02.000Z","size":17,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-10-12T07:42:44.158Z","etag":null,"topics":["fastify-plugin","telegraf","telegram"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/Eomm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2023-10-08T15:34:23.000Z","updated_at":"2024-06-09T10:03:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"e4521951-6e47-4900-bb54-45d431ba34ab","html_url":"https://github.com/Eomm/fastify-telegram","commit_stats":{"total_commits":7,"total_committers":1,"mean_commits":7.0,"dds":0.0,"last_synced_commit":"bd08851641b04e7a0402fd3fae897b7097c427bc"},"previous_names":["eomm/fastify-telegram"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eomm%2Ffastify-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eomm","download_url":"https://codeload.github.com/Eomm/fastify-telegram/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233408229,"owners_count":18671814,"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":["fastify-plugin","telegraf","telegram"],"created_at":"2024-10-05T07:20:46.514Z","updated_at":"2025-09-17T16:32:36.711Z","avatar_url":"https://github.com/Eomm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fastify-telegram\n\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n[![ci](https://github.com/Eomm/fastify-telegram/actions/workflows/ci.yml/badge.svg)](https://github.com/Eomm/fastify-telegram/actions/workflows/ci.yml)\n\nCreate and manage a Telegram bot easily.\n\nThis plugin is a good wrapper around [Telegraf](https://telegraf.js.org/) built by a Fastify maintainer.\n\nWhy you should use this plugin compared to what you can find on Google?\n\n- All the blog posts and tutorials I found are outdated and use old versions of Telegraf\n- The mentioned tutorials start **2** HTTP servers, one for Fastify and one for Node.js HTTP server, because the Telegram wrapper starts its own HTTP server. This is just a waste of resources.\n\nThis plugin instead:\n\n- Integrates the Telegram bot into the Fastify HTTP server\n- You can use all the Fastify features, like hooks and decorators\n- It has good utilities to manage errors and the telegram features (such as [polling mode](https://core.telegram.org/bots/api#getupdates))\n\n\n## Install\n\n```\nnpm install @eomm/fastify-telegram\n```\n\n### Compatibility\n\n| Plugin version | Fastify version | Telegraf version |\n| ------------- |:---------------:| ---------------:|\n| `^1.0.0` | `^4.0.0` | `^4.0.0` |\n\n## Usage\n\nWhen you register the plugin, it will add a decorator to the Fastify instance.\n\nYou can use it to access the [Telegraf](https://telegraf.js.org/) instance and configure your bot:\n\n```js\nconst fastify = require('fastify')\nconst fastifyTelegram = require('@eomm/fastify-telegram')\n\nasync function run () {\n  const app = fastify({\n    pluginTimeout: 10_000 // suggestion: increase the timeout\n  })\n\n  await app.register(fastifyTelegram, {\n    botToken: '123-abc', // [required] it must be a valid bot token\n\n    // [required] in webhook mode: the base url of your webhook\n    // [optional] in long polling mode: undefined\n    baseUrl: 'https://example.come',\n\n    // [optional]: customize the decorator name\n    decoratorBotName: 'telegramBot',\n\n    // [optional] this string is used to validate the incoming request\n    // Ref: https://core.telegram.org/bots/api#setwebhook\n    webhookSecret: 'secret',\n\n    // [optional]: the polling mode requires an health check that slows down the startup\n    // you can customize the max milliseconds to wait for the health check to pass\n    waitForHealthPolling: 3_000, // default: app.initialConfig.pluginTimeout / 6\n\n    // [optional] this function is called when an error is not handled\n    // by default it logs the error using `fastify.log.error`\n    // Ref: https://telegrafjs.org/index.html#/?id=error-handling\n    onUnhandledError: (err, ctx) =\u003e {\n      console.log(`Ooops, encountered an error for ${ctx.updateType}`, err)\n    }\n  })\n\n  // `app.telegramBot` is a Telegraf instance\n  // Now you can start using it:\n  app.telegramBot.on('text', (ctx) =\u003e ctx.reply('Hello World'))\n\n  await app.listen({ port: 3001 })\n}\n\nrun()\n```\n\n### Webhook mode\n\nIn this mode, the Telegram bot will send the updates to your server, so the plugin must know the public base url of your server.\n\nThen, it will register a POST route at the url `/telegraf/\u003csecretPath\u003e` where `\u003csecretPath\u003e` is a random string generated by Telegraf.\n\nYou can read the Webhook secret path from the `app.telegramWebhook` decorator.\n\n### Long polling mode\n\nIn this mode, the plugin will start a long polling process that will fetch the updates from the Telegram server by calling the method [`getUpdates`](https://core.telegram.org/bots/api#getupdates).\n\nThe `timeout` is set to `50` seconds by default, and you can't change it: it's a [Telegraf limitation](https://github.com/telegraf/telegraf/blob/c38ecc32a839470efd8691cd121ab933117fba76/src/core/network/polling.ts#L31).\n\n## Options\n\nYou can pass the following options to the plugin:\n\n- `botToken`: [required] it must be a valid bot token\n- `baseUrl`: [required] in webhook mode: the base url of your webhook; in long polling mode: undefined\n- `decoratorBotName`: [optional] customize the decorator name\n- `webhookSecret`: [optional] this string is used to validate the incoming request\n- `onUnhandledError`: [optional] this function is called when an error is not handled by default it logs the error using `fastify.log.error`\n\n## Decorators\n\nThe plugin adds the following decorators to the Fastify instance:\n\n- `app.telegramBot`: the [Telegraf](https://telegraf.js.org/) instance\n- `app.telegramWebhook`: the webhook secret path (only in webhook mode)\n\n\n## License\n\nCopyright [Manuel Spigolon](https://github.com/Eomm), Licensed under [MIT](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feomm%2Ffastify-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feomm%2Ffastify-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feomm%2Ffastify-telegram/lists"}