{"id":15605222,"url":"https://github.com/david-lor/telegrambot-webhook-updates-receiver-service","last_synced_at":"2025-03-29T14:13:49.137Z","repository":{"id":51318210,"uuid":"342690350","full_name":"David-Lor/TelegramBot-Webhook-Updates-Receiver-Service","owner":"David-Lor","description":"Proof of Concept of a Service to receive Telegram Bot updates through Webhook and publish/enqueue them on a message broker","archived":false,"fork":false,"pushed_at":"2022-11-13T12:59:34.000Z","size":186,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-04T14:47:52.103Z","etag":null,"topics":["python","python-3","python-webhook","python3","telegram","telegram-bot","telegram-bot-api","telegram-bots","webhook","webhooks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/David-Lor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-26T20:15:36.000Z","updated_at":"2022-11-13T12:58:58.000Z","dependencies_parsed_at":"2023-01-23T00:01:11.950Z","dependency_job_id":null,"html_url":"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/David-Lor%2FTelegramBot-Webhook-Updates-Receiver-Service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/David-Lor%2FTelegramBot-Webhook-Updates-Receiver-Service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/David-Lor%2FTelegramBot-Webhook-Updates-Receiver-Service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/David-Lor%2FTelegramBot-Webhook-Updates-Receiver-Service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/David-Lor","download_url":"https://codeload.github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246193267,"owners_count":20738452,"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":["python","python-3","python-webhook","python3","telegram","telegram-bot","telegram-bot-api","telegram-bots","webhook","webhooks"],"created_at":"2024-10-03T04:03:13.042Z","updated_at":"2025-03-29T14:13:49.117Z","avatar_url":"https://github.com/David-Lor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Bot Updates Receiver Service\n\nThe objective of this project is to build a microservice that receives updates from a Telegram Bot through Webhook, and publishes them on a message broker or queue system (like MQTT, AMQP, Kafka or Redis), to be consumed by one or more processing microservices.\n\n**This project is currently a Proof of Concept.**\n\n## Architecture\n\nA very basic architecture would involve three services:\n\n- A message broker/queue service\n- The Receiver Service (current repository)\n- A Consumer Service, that consumes updates and processes them, including all the business logic behind the bot - ending with calls to the Telegram Bot API to send responses to the users\n\n![Architecture diagram](docs/architecture.svg)\n\n## Why\n\n### Advantages\n\n- The Consumer Services can be developed without having to deal with the development and/or implementation of the Webhook updates receiver\n- Multiple consumer microservices can be deployed, for redundancy and/or to keep different business logic\n\n### Disadvantages\n\n- Maintaining multiple microservices can be overkill in many use-cases\n- If using multiple Consumer Services, synchronization between them must be implemented if required (e.g. for caching data or keeping context of messages received)\n- Some libraries do not allow injecting arbitrary Telegram Bot Updates JSON data\n\n## Getting started\n\n### Webhook\n\nThe following steps will start running the service out of the box, using Docker and ngrok:\n\n1. You must own a Telegram bot. If not, create it from BotFather. You will need the bot token.\n2. Download ngrok, and start running it as following:\n   ```bash\n   ./ngrok http 8025\n   ```\n3. Copy the `sample.env` file as `.env`, and complete the following settings\n   - `TELEGRAM_TOKEN` with you bot token\n   - `WEBHOOK_DOMAIN` with the domain that ngrok is currently using, including `https://` (notice that ngrok free plan will change the domain periodically)\n4. Start running the webhook receiver service:\n   ```bash\n   docker run --rm -it -p 8025:8025 -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" --env-file=\".env\" davidlor/python-git-app:slim\n   ```\n5. Send something to your bot. You should see some output on the container\n\n#### Example: pytelegrambotapi + redis (webhook)\n\nA Telegram Bot backend example is available [here](https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service/tree/example/pytelegrambotapi%2Bredis/telegrambot_client). It can be deployed with the following commands:\n\n```bash\n# Start ngrok\n./ngrok http 8025\n\n# Add the REDIS_URL \u0026 REDIS_QUEUE_NAME settings (for both server \u0026 client) - Ensure you already have copied and modified a .env file, including the webhook endpoint with the current ngrok domain!\necho \"REDIS_URL=redis://telegrambot-redis:6379\" \u003e\u003e .env\necho \"REDIS_QUEUE_NAME=TelegramBotQueue\" \u003e\u003e .env\n\n# Create a docker network for the services\ndocker network create telegrambot-net\n\n# Start the Redis server\ndocker run -d --name=telegrambot-redis --network=telegrambot-net redis\n\n# Start the webhook server (receive updates through webhook, enqueue on Redis)\ndocker run -d --name=telegrambot-receiver -p 8025:8025 --net=telegrambot-net -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" --env-file=\".env\" davidlor/python-git-app:slim\n\n# Start the Telegram bot backend (read updates from Redis queue, process them)\ndocker run -d --name=telegrambot-backend --net=telegrambot-net -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" -e GIT_BRANCH=\"example/pytelegrambotapi+redis\" --env-file=\".env\" davidlor/python-git-app:slim\n```\n\nAlternatively, you can run the [self-hosted Telegram Bot API](https://github.com/lukaszraczylo/tdlib-telegram-bot-api-docker) with the `--local` argument, to avoid dealing with SSL certificates.\n\n### Polling\n\nThe following steps will start running the service out of the box, using Docker and fetching the updates using the long-polling method, instead of setting up a webhook:\n\n1. You must own a Telegram bot. If not, create it from BotFather. You will need the bot token.\n2. Copy the `sample.env` file as `.env`, and complete the following settings\n   - `TELEGRAM_TOKEN` with you bot token\n3. Start running the receiver service:\n    ```bash\n    docker run --rm -it -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" --env-file=\".env\" davidlor/python-git-app:slim\n    ```\n4. Send something to your bot. You should see some output on the container\n\n#### Example: pytelegrambotapi + redis (polling)\n\n```bash\n# Add the REDIS_URL \u0026 REDIS_QUEUE_NAME settings (for both server \u0026 client) - Ensure you already have copied and modified a .env file!\necho \"REDIS_URL=redis://telegrambot-redis:6379\" \u003e\u003e .env\necho \"REDIS_QUEUE_NAME=TelegramBotQueue\" \u003e\u003e .env\n\n# Create a docker network for the services\ndocker network create telegrambot-net\n\n# Start the Redis server\ndocker run -d --name=telegrambot-redis --network=telegrambot-net redis\n\n# Start the receiver service (receive updates through long-polling, enqueue on Redis)\ndocker run -d --name=telegrambot-receiver --net=telegrambot-net -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" --env-file=\".env\" davidlor/python-git-app:slim\n\n# Start the Telegram bot backend (read updates from Redis queue, process them)\ndocker run -d --name=telegrambot-backend --net=telegrambot-net -e GIT_REPOSITORY=\"https://github.com/David-Lor/TelegramBot-Webhook-Updates-Receiver-Service\" -e GIT_BRANCH=\"example/pytelegrambotapi+redis\" --env-file=\".env\" davidlor/python-git-app:slim\n```\n\n## Settings\n\nSettings are defined using environment variables, or a .env file. Variables defined as environment variables will override those defined in the .env file.\n\n- **General**\n  - **ENV_FILE**: (default: `.env`) path of the .env file to load settings from. If the file does not exist or cannot be found, settings will not load from .env file.\n  - **PUBLISHER_CONNECT_TIMEOUT**: (default: `10`) timeout in seconds for all publishers to initialize/connect on service startup.\n  - **TEARDOWN_TIMEOUT**: (default: `10`) timeout in seconds for all teardown operations, executed when service is closed.\n- **Webhook**\n  - **WEBHOOK_DOMAIN**: (optional) domain where webhook is served, including \"https://\" or \"http://\", but NOT the endpoint. If not set, the updates will be acquired using Telegram getUpdates long-polling.\n  - **WEBHOOK_ENDPOINT**: (default: `random`) endpoint where Telegram will send Webhook POST requests. With the domain, forms the webhook URL that is sent to Telegram to send bot updates to. Can be one of:\n    - `random`: generate a random UUID4 string as endpoint, each time the application starts\n    - `token`: use the bot token as endpoint\n    - any other valid string will be used as-is as endpoint\n  - **WEBHOOK_BIND**: (default: `0.0.0.0`) address to host the webhook server on.\n  - **WEBHOOK_PORT**: (default: `8000`) port to host the webhook server on.\n  - **WEBHOOK_STATUS_ENDPOINT**: (default: `true`) if false, do not serve a `/status` endpoint, accessible from any host to verify that the server is accessible.\n  - **WEBHOOK_PUBLISH_TIMEOUT**: (default: `5`) timeout in seconds for publishing webhook received data in all publishers.\n  - **WEBHOOK_LIMIT_SUBNETS**: (optional) comma-separated list of networks, with the format `ip/mask`, that can be used for limiting access to the webhook endpoint to hosts from these subnetworks. The subnetworks used by Telegram, as stated [in their documentation](https://core.telegram.org/bots/webhooks), would be `149.154.160.0/20,91.108.4.0/22` (keep in mind that these could change in the future). If not specified, no limitations will be applied.\n- **Telegram**\n  - **TELEGRAM_TOKEN**: (**required**) Telegram Bot token.\n  - **TELEGRAM_DELETE_WEBHOOK**: (default: `true`) if true, delete the webhook when the application closes.\n  - **TELEGRAM_API_URL**: (default: `https://api.telegram.org`) base URL for the Telegram Bot API, may be changed for using a self-hosted Bot API.\n  - **TELEGRAM_POLLING_TIMEOUT**: (default: `10`) timeout in seconds for Telegram getUpdates long-polling individual requests.\n- **Redis**\n  - **REDIS_URL**: (optional) if specified, put bot updates on a queue of the given Redis server. URL example: `redis://localhost:6379`.\n  - **REDIS_QUEUE_NAME**: (default: `telegram_bot`) name of the Redis queue where bot updates are put.\n\n## Upcoming features...\n\n- Refactor example (do not use other branch) when `davidlor/python-git-app` Docker image supports arbitrary Python script running\n\n## Changelog\n\n_Versions prior 1.0.0 are considered experimental and breaking changes may occur on MINOR versions (0.x)_\n\n- 0.2.0\n  - AMQP integration\n  - Support for Telegram getUpdates long-polling\n- 0.1.0\n  - Final version\n  - Redis integration\n- 0.0.1\n  - Initial PoC script\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavid-lor%2Ftelegrambot-webhook-updates-receiver-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavid-lor%2Ftelegrambot-webhook-updates-receiver-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavid-lor%2Ftelegrambot-webhook-updates-receiver-service/lists"}