{"id":13627516,"url":"https://github.com/NivEz/telenode","last_synced_at":"2025-04-16T23:33:11.307Z","repository":{"id":65799002,"uuid":"591323472","full_name":"NivEz/telenode","owner":"NivEz","description":"Lightweight Telegram API framework for Node.js","archived":false,"fork":false,"pushed_at":"2024-12-25T23:08:40.000Z","size":193,"stargazers_count":41,"open_issues_count":0,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T03:38:29.505Z","etag":null,"topics":["node-js","nodejs","npm","telegram","telegram-bot","telegram-bot-api"],"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/NivEz.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-01-20T13:33:42.000Z","updated_at":"2025-03-25T02:08:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"4cddd84b-b003-4a7e-a957-961fe5802a19","html_url":"https://github.com/NivEz/telenode","commit_stats":{"total_commits":80,"total_committers":4,"mean_commits":20.0,"dds":0.03749999999999998,"last_synced_commit":"035022b1e3e28281f839b3841ffa063d74db55de"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NivEz%2Ftelenode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NivEz%2Ftelenode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NivEz%2Ftelenode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NivEz%2Ftelenode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NivEz","download_url":"https://codeload.github.com/NivEz/telenode/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249288027,"owners_count":21244717,"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":["node-js","nodejs","npm","telegram","telegram-bot","telegram-bot-api"],"created_at":"2024-08-01T22:00:35.073Z","updated_at":"2025-04-16T23:33:11.100Z","avatar_url":"https://github.com/NivEz.png","language":"JavaScript","funding_links":[],"categories":["Projects by main language"],"sub_categories":["javascript"],"readme":"# Telenode\n\nLightweight Telegram API framework for Node.js\n\n![npm package](https://img.shields.io/badge/-grey?logo=telegram)\n[![npm package](https://img.shields.io/npm/v/telenode-js?color=orange\u0026logo=npm)](https://www.npmjs.org/package/telenode-js)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-green.svg)](https://raw.githubusercontent.com/NivEz/telenode/main/LICENSE)\n![total downloads](https://img.shields.io/npm/d18m/telenode-js.svg)\n![monthly downloads](https://img.shields.io/npm/dm/telenode-js.svg)\n\n---\n\n## Features\n\n✅ Explicit messages handlers\n\u003cbr\u003e\n✅ Fallback messages handler (empty string - any messages)\n\u003cbr\u003e\n✅ Regex matching on text messages\n\u003cbr\u003e\n✅ Buttons support (inline keyboard, reply keyboard and remove reply keyboard)\n\u003cbr\u003e\n✅ Fallback handler for any button (empty string - button callback_data)\n\u003cbr\u003e\n✅ Edit inline keyboards\n\u003cbr\u003e\n✅ Secret token support\n\u003cbr\u003e\n✅ Long polling support\n\u003cbr\u003e\n✅ Sending chat action\n\n## Getting started\n\n#### Complete example can be found [here](https://github.com/NivEz/movie-info-bot)\n\n### Installation\n\n```shellscript\nnpm install telenode-js\n```\n\n### Install dependencies\n\nIn order to reduce the `node_modules` size `dotenv` (for environment variables) and `express` (for local development /\ndeployment) packages are defined as `devDependencies`.\n\nYou don't have to use these packages if you don't want to, and you can use them only for local development if you choose\nso.\n\u003cbr\u003e\nIf you do choose to work with these packages, install them manually:\n\n```shellscript\nnpm install express dotenv\n```\n\nOr for serverless deployments install express as a dev dependency (to use in your local development environment)\ninstead:\n\n```shellscript\nnpm install express --save-dev\n```\n\n### Set webhook\n\nIn order to listen to updates from Telegram servers you have to set up a webhook.\n\u003cbr\u003e\nTo use the `npx set-webhook` command you should provide the webhook parameter and api token.\nYou can do that by:\n\n1. Setting the `WEBHOOK` and `API_TOKEN` environment variables (`SECRET_TOKEN` is optional).\n2. Storing them in `.env` file (`SECRET_TOKEN` is optional).\n3. Use the `--apiToken` and `--webhook` command arguments (`--secretToken` is optional).\n\nYou also can provide the secret token parameter if you choose to.\n\nThen you can execute the following command:\n\n```shellscript\nnpx set-webhook\n```\n\n* If you want to delete a webhook use the command:\n\n```shellscript\nnpx delete-webhook\n```\n\n### Long polling\n\nIf you prefer to use long polling method over creating a server with webhook you can use the `startLongPolling` method instead of `createServer`. If you have a webhook set up already, you need to delete it, you can use the `npx delete-webhook` command to delete it.\n\n\u003cbr\u003e\nThe method accepts `pollingDelay` - a number that represents milliseconds (must be at least 50ms).\n\u003cbr\u003e\nBy default the long polling mechanism will ignore all previous updates (`cleanPreviousUpdates` by default is `true`). You can toggle off `cleanPreviousUpdates` if you want to by setting it as `false` when you call `startLongPolling`.\n\u003cbr\u003e\nYou also can stop the long polling while it's running by setting `bot.useLongPolling` to `false`.\n\u003cbr\u003e\nYou can view an example of long polling usage [here](https://github.com/NivEz/telenode/tree/main/examples/long-polling.js).\n\nNote that long polling is usually not recommended and webhook is preferred for most use cases.\n\n### Usage\n\n```js\nconst Telenode = require('telenode-js');\nrequire('dotenv').config();\n\nconst bot = new Telenode({\n\tapiToken: process.env.API_TOKEN,\n});\n\nbot.createServer(); // spins up an express server\n\nbot.onTextMessage('hello', async (messageBody) =\u003e {\n\tconsole.log(messageBody);\n\tawait bot.sendTextMessage('hello back', messageBody.chat.id);\n});\n```\n\nIn this example the bot will listen only to 'hello' text messages and will respond to the user 'hello back'. Any other\nmessage will be ignored.\n\n- Note that `bot.createServer()` method requires `express`, and we are using `dotenev` as well which both are not\n  installed automatically with `Telenode`.\n\nAdditional examples can be found in the [examples folder](https://github.com/NivEz/telenode/tree/main/examples).\n\n### Webhook security with secret token\n\nYou can secure your webhook with a secret token via the `setWebhook` method. You can do that by creating\na `SECRET_TOKEN` variable in the `.env` file of your project (or environment variable) and run the `npx set-webhook`\ncommand. The command will\ntell Telegram servers to send the secret token in each request to your webhook as `x-telegram-bot-api-secret-token`\nheader.\n\nIn order for the bot to use the secret token you need to pass to the `Telenode` class you instanciate the `secretToken`\nparameter.\n\nYou will have to pass a `secretToken` parameter to the `telenodeHandler` method as well.\n\nYou can pass a third parameter called `unauthorizedCallback` - a callback that will fire in case the request wasn't\nauthorized.\n\nYou can find the example in\nthe [secretToken.js example](https://github.com/NivEz/telenode/tree/main/examples/secretToken.js) and the implementation\nin [src/server.js](https://github.com/NivEz/telenode/tree/main/src/server.js) as well.\n\n---\n\n## Run feature examples:\n\nAfter you have set your webhook you can play and test the `Telenode` features.\n\nEach feature of `Telenode` is demonstrated in an example file inside the `examples` folder (inside `node_modules` if you\ninstalled `Telenode`).\n\u003cbr\u003e\nYou can run an example from the `telenode-js` directory inside `node_modules` by using the command:\n\n```shellscript\nnpm run dev --file=\u003cexample\u003e\n```\n\nYou might need `nodemon` and `dotenv` installed as dev dependencies to run the examples with the command above.\n\n---\n\n## Deployment:\n\nSince these days it is common to use serverless backend services, you can choose how the bot will work - or\nwith `express` or with the `HTTP` engine of the serverless provider.\n\nIn order to spin up an express server you should use the command `bot.createServer()` - this is useful for deployments\non VMs / containers / on-premise.\n\nYou can pass an object as options for `createServer`. Currently, it supports `port` and `unauthorizedCallback` (if you\nuse secret token) - e.g:\n\n```js\nbot.createServer({ port: 4000 }) // the default is 3000\n```\n\nIn the other hand, if you want to deploy on serverless backend you need to use `bot.telenodeHandler` method and pass to\nit the request object.\nYou will probably have something like this:\n\n```js\nfunctions.https.onCall((req, res) =\u003e {\n    const secretToken = req.headers['x-telegram-bot-api-secret-token'];\n    bot.telenodeHandler(req.body, secretToken, unauthorizedHandler);\n    res.end();\n});\n```\n\nNote that on serverless you should extract by your own the `secretToken` since every serverless service might process\nthe `req` object differently.\n\n---\n\n## Contributions:\n\nIf you want to develop a new feature you should create an example file under the examples' folder that demonstrates how\nto use the feature.\n\n---\n\n## TODO's\n\n- [ ] Direct respond function in message handler without passing chat ID\n- [ ] Chat ID handlers\n- [ ] Arguments validations\n- [ ] Optimize Telegram API requests\n- [ ] Add extra security with query params token\n- [ ] Add tests\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNivEz%2Ftelenode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNivEz%2Ftelenode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNivEz%2Ftelenode/lists"}