{"id":25572840,"url":"https://github.com/arg0wak/telegram-hooker","last_synced_at":"2026-02-20T19:03:06.796Z","repository":{"id":278523058,"uuid":"913851328","full_name":"arg0WAK/telegram-hooker","owner":"arg0WAK","description":"In this package has a core framework that facilitates webhook management for Telegram bots. It is compatible with various frameworks (Express, Fastify, Koa, Hapi) and provides a set of tools you can use to manage and log your bots messages.","archived":false,"fork":false,"pushed_at":"2025-02-24T16:19:50.000Z","size":1028,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-07T14:49:03.667Z","etag":null,"topics":["express","fastify","hapi","koa","package","telegram-api","telegram-bot","telegram-webhook"],"latest_commit_sha":null,"homepage":"https://arg0wak.github.io/telegram-hooker/documentation/index.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arg0WAK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/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":["arg0WAK"],"patreon":"arg0WAK","buy_me_a_coffee":"arg0wak","custom":["https://ppr.ist/lLv7ANv5"]}},"created_at":"2025-01-08T13:28:17.000Z","updated_at":"2025-03-19T19:44:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"e4b86a72-fb6c-44d0-8e6a-32ea4388c52a","html_url":"https://github.com/arg0WAK/telegram-hooker","commit_stats":null,"previous_names":["arg0wak/telegram-hooker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arg0WAK/telegram-hooker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arg0WAK%2Ftelegram-hooker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arg0WAK%2Ftelegram-hooker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arg0WAK%2Ftelegram-hooker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arg0WAK%2Ftelegram-hooker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arg0WAK","download_url":"https://codeload.github.com/arg0WAK/telegram-hooker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arg0WAK%2Ftelegram-hooker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015924,"owners_count":26085778,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["express","fastify","hapi","koa","package","telegram-api","telegram-bot","telegram-webhook"],"created_at":"2025-02-21T01:18:03.388Z","updated_at":"2025-10-13T15:31:55.196Z","avatar_url":"https://github.com/arg0WAK.png","language":"TypeScript","funding_links":["https://github.com/sponsors/arg0WAK","https://patreon.com/arg0WAK","https://buymeacoffee.com/arg0wak","https://ppr.ist/lLv7ANv5"],"categories":[],"sub_categories":[],"readme":"  \u003cdiv align=\"center\"\u003e\n      \u003cimg src=\"https://arg0wak.github.io/gist/images/telegram-hooker/telegram.gif\" width=\"92px\"\u003e\n  \u003c/div\u003e\n  \u003ch1 align=\"center\"\u003etelegram-hooker\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n      Service designed to handle multiple Telegram webhooks.\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n      \u003cimg alt=\"Node 22.12.0\" src=\"https://img.shields.io/badge/Node-22.12.0-nodedotjs?logo=nodedotjs\u0026logoColor=white\"/\u003e\n      \u003cimg alt=\"Typescript\" src=\"https://img.shields.io/badge/TypeScript-blue?logo=typescript\u0026logoColor=white\"/\u003e\n      \u003cimg alt=\"Telegram\" src=\"https://img.shields.io/badge/@arg0WAK-blue?logo=telegram\u0026logoColor=white\"/\u003e\n      \u003ca target=\"_blank\" href=\"https://github.com/arg0WAK/telegram-hooker/tree/master\"\u003e\n      \u003cimg alt=\"Github\" src=\"https://img.shields.io/badge/Repository-gray?logo=Github\u0026logoColor=white\"/\u003e\u003c/a\u003e\n      \u003ca target=\"_blank\" href=\"https://github.com/arg0WAK/telegram-hooker/tree/master/examples\"\u003e\n      \u003cimg alt=\"Examples\" src=\"https://img.shields.io/badge/Examples-pink?logo=project\u0026logoColor=white\"/\u003e\u003c/a\u003e\n      \u003ca target=\"_blank\" href=\"https://arg0wak.github.io/telegram-hooker/documentation/index.html\"\u003e\n      \u003cimg alt=\"Docs\" src=\"https://img.shields.io/badge/Documentation-violet?logo=project\u0026logoColor=dark\"/\u003e\u003c/a\u003e\u003cbr/\u003e\n      \u003cimg alt=\"Express\" src=\"https://img.shields.io/badge/Express-black?logo=Express\u0026logoColor=white\"/\u003e\n      \u003cimg alt=\"Fastify\" src=\"https://img.shields.io/badge/Fastify-black?logo=Fastify\u0026logoColor=white\"/\u003e      \n      \u003cimg alt=\"Hapi\" src=\"https://img.shields.io/badge/Hapi-black?logo=Hapi\u0026logoColor=white\"/\u003e\n      \u003cimg alt=\"Koa\" src=\"https://img.shields.io/badge/Koa-black?logo=Koa\u0026logoColor=white\"/\u003e\n      \u003cbr/\u003e\n  \u003c/p\u003e\n\n## ⚙️ Getting Started\n\nIn this package has a core HTTP structure that facilitates webhook management for Telegram bots. It is compatible with various frameworks (Express, Fastify, Koa, Hapi) and provides a set of tools you can use to manage and log your bots messages.\n\n**You can manage all your workers in a single group, or each worker in their own private chat window.** If you planing to manage in a group, your main worker should have the permission to read the messages in the group **considering that all messages will be logged simultaneously on your server.**\n\n## ✨ Features\n\n- **Listens and processes webhook requests** from Telegram bots.\n\n- Supported with examples using the **starter structure of each framework for easy implementation.**\n- Optionally configurable **logging function is used to log all messages by default.**\n- Core based **has message deletion and message sending functions** available for each worker.\n- **Scalable bot configuration**\n- **Seamless and optional NGROK integration** (_re-tunnelled on every run for every employee._)\n- **Typescript** workspace **ready to build**.\n\n## 🚀 Installation\n\nThis package is tested ESM only. In Node.js (version 18+), install with npm according to your framework:\n\n**Pick a framework**\n\n```bash\nnpm i @telegram-hooker/core\n```\n\n```bash\nnpm i @telegram-hooker/express\n```\n\n```bash\nnpm i @telegram-hooker/fastify\n```\n\n```bash\nnpm i @telegram-hooker/hapi\n```\n\n```bash\nnpm i @telegram-hooker/koa\n```\n\n### Configure the Telegram Workers\n\nNote that you must add at least one bot before you build the project. To get details about your main worker's telegram configuration, make a GET request with any tool to the following endpoint with the API key of the bot you created via BotFather.\n\n```http\nGET https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getMe\n```\n\nResponse similar to the following response will be returned in result to the request sent.\n\n```javascript\n{\n  \"ok\": true,\n  \"result\": {\n    \"id\": 0123456789, // This is a chatId\n    \"is_bot\": true,\n    \"first_name\": \"BotName\",\n    \"username\": \"NameBot\",\n    \"can_join_groups\": true,\n    \"can_read_all_group_messages\": true,\n    \"supports_inline_queries\": false,\n    \"can_connect_to_business\": false,\n    \"has_main_web_app\": false\n  }\n}\n```\n\nWhen you create a group, you can access the **groupId** key by default if there is **only one administrator in the group**. So remember to store the groupId key immediately after creating the group. This may become a need in your future developments.\n\nTo access superGroupId, **bot must have administrator privileges in group where is in**. If you meet these requirements, send a message to the group where the bot is located.\n\nThen send a GET request to the following endpoint.\n\n```http\nGET https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/getUpdates\n```\n\nResponse similar to the following response will be returned in result to the request sent.\n\n**If you don't get the expected answer, be sure to /start the bot via private chat.**\n\n```javascript\n{\n  \"ok\": true,\n  \"result\": [\n   {\n      \"update_id\": 0123456789,\n      \"message\": {\n        \"message_id\": 4883,\n        \"from\": {\n          \"id\": 0123456789, // Your chatId\n          \"is_bot\": false,\n          \"first_name\": \"D\",\n          \"username\": \"arg0WAK\",\n          \"language_code\": \"en\"\n        },\n        \"chat\": {\n          \"id\": -1000123456789, // This is a superGroupId\n          \"title\": \"0x62\",\n          \"type\": \"supergroup\"\n        },\n        \"date\": 1735604231,\n        \"text\": \"Hello, Github!\"\n      }\n    }\n  ]\n}\n```\n\n### Import module\u003cbr/\u003e\n\n[Check Import Details](https://arg0wak.github.io/telegram-hooker/documentation/index.html#types-using-with-typescript)\n\n### Configure the createHook function\u003cbr/\u003e\n\nImplement a create hook function to your project. If you are using a Typescript environment, make sure you specify the appropriate type for the framework you depend on.\n\nThe following example reflects its use in a simple node-http environment. Refer to examples for other frameworks.\n\n```javascript\n// Create a new hook tree\nconst worker: TelegramHookerCore = createHook({\n  port: port, // Define your server port\n  proxy: false, // If you want to use a proxy, define your URL with a string type in the proxy key (e.g. 'https://proxy.arg0.dev')\n  installRoute: '/webhook/specify-your-route', // Recommended usage starts with '/webhook' (e.g. '/webhook/arg0WAK')\n  token: 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u', // Define your bot token for Frontend API\n  ngrokAuthToken: 'NGROK_AUTH_TOKEN', // Define your ngrok authtoken\n  enableFileLogs: true, // If you want to save logs of messages received from Telegram\n  enableCommandLineLogs: false, // If you don't want to see logs in the console\n  logsDirectory: 'logs/arg0', // Define the directory for logs this worker\n  groupId: '-1234567890', // Define your group id\n  superGroupId: '-123456789124', // Define your supergroup id\n  workers: {\n    // Define your main worker (You must have at least one main worker.)\n    main_worker: {\n      userName: 'MainBot', // Define your worker username\n      token: 'a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u', // Define your worker token\n      chatId: '-123456789' // Define your chat id\n    }\n  },\n  ipAddress: '142.250.189.238', // Define your server IP address (e.g. '142.250.189.238')\n  handShake: true, // If you want to use a certificate, set it to true and define the path to the certificate\n  certificatePath: 'path/to/certificate.pem', // If handShake is true you must define the path to the certificate\n  maxConnections: 100, // Define the maximum number of connections\n  dropPendingUpdates: true, // If you want to drop pending updates, set it to true (recommended)\n  // Define the allowed updates (probably you need to only use 'message' and 'callback_query')\n  allowedUpdates: [\n    'message',\n    'edited_message',\n    'channel_post',\n    'edited_channel_post',\n    'inline_query',\n    'chosen_inline_result',\n    'callback_query',\n    'shipping_query',\n    'pre_checkout_query',\n    'poll',\n    'poll_answer',\n    'my_chat_member',\n    'chat_member'\n  ],\n  secretToken: true // If you want to use a secret token equal Bearer token, set it to true. Otherwise, you can define different token\n})\n```\n\n## Create Server\n\nUse a createRoute middleware so that the Hook functionality can be attached.\n\n```javascript\n// Create node-http server\nconst server = http.createServer((req: IncomingMessage, res: ServerResponse) =\u003e {\n  // Handle webhook requests\n  worker.handleRequest(req, res) // Its will be work like a middleware\n\n  /* Continue */\n})\n```\n\nDetermine the routes that your workers will communicate separately for each worker. This will allow you to manage messages from workers more effectively. In this case, the route expected by the API should be as follows. In a simple Node HTTP server, you need to access the body in the request object in order to correctly process the activities on Telegram. You can consider using a body parser in this context.\n\n```javascript\n  // Create worker route for tunneling (e.g. req.url === your-webhook-install-path/your-worker-username)\n  else if (req.url === worker.config.installRoute + '/' + worker.config.workers.main_worker.userName) {\n    // Process your bot actions (for req.body.message actions you need to parse the request body)\n    console.log('Bot is active!')\n\n    // Make sure you return a response with the code 200 at the end of the process. Otherwise, the Telegram API will send the same message again after about a minute.\n    res.writeHead(200, { 'Content-Type': 'application/json' })\n    res.end(JSON.stringify({ status: 'ok' }))\n  }\n```\n\nUse your optional routes as follows.\n\n```javascript\n// Your any routes\nif (req.url === '/') {\n  res.statusCode = 200\n  res.setHeader('Content-Type', 'text/plain')\n  res.end('This is a webhook server.')\n}\n```\n\nIf you want to assign a response in case 404 by default, specify this below the structure. This will only work with your optional routes other than installRoute.\n\n```javascript\n// Handle your 404 middleware\nif (!res.headersSent \u0026\u0026 !req.handled) {\n  res.statusCode = 404\n  res.setHeader('Content-Type', 'text/plain')\n  res.end('404 Not Found')\n}\n```\n\nInstall your hooks by accessing the url address you defined in installRoute via Browser. Bearer token you was defined before is required.\n\n```http\nGET https://\u003cNGROK_OR_PROXY_URL\u003e/webhook/specified-your-route/install\n```\n\n\u003cimg src=\"https://arg0wak.github.io/gist/images/telegram-hooker/zzv98-mc0dl.gif\" width=\"100%\" alt=\"Telegram Hooker\" /\u003e\n\n## 📃 License\n\nTelegram Hooker is distributed under a BSL Licence which allows its unlimited non-commercial use. The code in this repository automatically becomes Open Source for commercial use (Apache 2.0 Licence) after 4 years. Some public repositories that complement this repository (examples, libraries, linkers, etc.) are licensed as Open Source under the MIT licence.\n\n## 🔖 Contribution Guidelines\n\nIf you develop a library or linker that you want to integrate with this repo, I recommend that you first release it as a separate repo on the **MIT licence**.\n\nFor all concerns regarding basic **Telegram Hooker functionalities**, Issues are encouraged. For more information, feel free to contact me at my [Telegram address](https://t.me/arg0WAK) **if you do not receive a response to your Github cases.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farg0wak%2Ftelegram-hooker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farg0wak%2Ftelegram-hooker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farg0wak%2Ftelegram-hooker/lists"}