{"id":16108754,"url":"https://github.com/yshalsager/telegram-feedback-bot","last_synced_at":"2025-03-17T18:30:16.856Z","repository":{"id":204688054,"uuid":"712101923","full_name":"yshalsager/telegram-feedback-bot","owner":"yshalsager","description":"A Telegram feedback bots builder with topics support.","archived":false,"fork":false,"pushed_at":"2024-10-22T03:56:44.000Z","size":403,"stargazers_count":9,"open_issues_count":7,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-22T16:38:06.005Z","etag":null,"topics":["livegram","livegram-bot","pyrogram","pyrogram-bot","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","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/yshalsager.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-30T19:46:07.000Z","updated_at":"2024-10-22T03:56:44.000Z","dependencies_parsed_at":"2024-10-22T20:31:05.876Z","dependency_job_id":null,"html_url":"https://github.com/yshalsager/telegram-feedback-bot","commit_stats":null,"previous_names":["yshalsager/telegram-feedback-bot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshalsager%2Ftelegram-feedback-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshalsager%2Ftelegram-feedback-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshalsager%2Ftelegram-feedback-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yshalsager%2Ftelegram-feedback-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yshalsager","download_url":"https://codeload.github.com/yshalsager/telegram-feedback-bot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243875083,"owners_count":20361941,"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":["livegram","livegram-bot","pyrogram","pyrogram-bot","telegram","telegram-bot"],"created_at":"2024-10-09T19:28:22.959Z","updated_at":"2025-03-17T18:30:16.556Z","avatar_url":"https://github.com/yshalsager.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram Feedback Bots Builder\n\nA bot that builds feedback Telegram bots like Livegram but with topics support.\n\n**Note**: If you don't need a builder and just want one feedback bot, checkout [standalone](https://github.com/yshalsager/telegram-feedback-bot/tree/standalone) branch.\n\n## Features\n\n### Builder\n\n- Create new feedback bots.\n- Manage existing bots.\n    - Delete bot.\n    - Change its token.\n    - Change its group.\n    - Change bot messages (start, receive feedback, sent message feedback).\n- Admin options:\n    - Whitelist users and remove them, disabled by default.\n    - Broadcast messages to all users.\n    - Restart all bots.\n    - Enable or disable bots (via /manage).\n    - Update bot code (via /update).\n- Multi-language support (automatically selected based on Telegram language).\n\n### Bots\n\n- Receive feedback messages from users.\n- Each user has its own topic that messages are sent to, so admins can reply to each user individually and chat history\n  is clear.\n- General topic messages aren't sent to users, so admins can discuss without spamming users.\n- Admins can broadcast messages to all users.\n- Bot statistics of users, received and sent messages.\n\n## Configuration\n\nCreate a .env file and fill it with requires values from `mise.toml` env section.\n\n```toml\n[env]\n# the Telegram bot token https://telegram.me/BotFather\nBOT_TOKEN = '0000000000:aaaaaaaaaaaaaaaaaaaa'\n# to connect to MTProto, which we use to upload media files (retrieve from https://my.telegram.org)\nAPI_ID = '0000000'\nAPI_HASH = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'\n# the Telegram account IDs that will have administrator permissions of the bot\nBOT_ADMINS = '000000,000000,000000'\n# Chat that will receive the bot messages\nCHAT_ID = '-10000000000'\n# Group topic that will be used for bot logs\nLOG_TOPIC_ID = 1\n# Require admin approval to add new bot\nNEW_BOT_ADMIN_APPROVAL = \"true\"\nDEBUG = 1\n```\n\nCreate an encryption key with `mise r generate-encryption-key`\nor `python -c \"from secrets import token_bytes; print(token_bytes(32).hex())\"`\nand update `ENCRYPTION_KEY` variable.\n\n## Running\n\n### Docker\n\n- `docker compose up`\n\n### Poetry\n\n- `poetry install`\n- `python3 -m src`\n\n## Usage\n\n### Builder\n\n- `/start`: sends the main menu to create and manage bots.\n- `/whitelist [user_id]`: adds new users to the whitelist.'\n- `/manage`: manage users and bots by admin.\n- `/broadcast`: sends a message to all bot users. Send as a reply to a message previously sent to the bot.\n- `/restart`: restarts the bot.\n- `/update`: updates the bot code.\n\n### Bots\n\n- `/start`: says hello.\n- Send a message, it will be forwarded to the bot owner or group.\n- Owner can reply to the message and it will be forwarded to the user.\n- `/broadcast`: sends a message to all bot users. Send as a reply to a message previously sent to the bot.\n- `/stats`: shows bot statistics.\n\n## How it works?\n\n- Instead of using Telegram bots HTTP API (with long polling or webhooks), we\n  use [MTProto](https://core.telegram.org/mtproto) directly via Pyrogram, since Pyrogram uses persistent connections via\n  TCP sockets to interact with Telegram servers instead of actively asking for updates.\n- The builder bot is responsible for creating Pyrogram clients for bots, and managing them.\n- Only builder bot owner can enable or disable bots. Builder bot users can create their own feedback bots and manage\n  them.\n- SQLAlchemy and Alembic are used for database management. When a new bot is created, a new database is created with\n  Alembic to ensure the schema is up to date for all bots.\n- Feedback bot forwards messages from users to its created bot owner or group, so it can be replied to. The bot will\n  only send the reply to the user if message is a reply to user's message.\n\n## Acknowledgements\n\n### Libraries, Tools, etc\n\n- [Python](https://www.python.org/)\n- [Pyrogram](https://github.com/Mayuri-Chan/pyrofork)\n- [Plate](https://github.com/delivrance/plate)\n- [regex](https://github.com/mrabarnett/mrab-regex)\n- [SQLAlchemy](https://www.sqlalchemy.org/)\n- [Alembic](https://alembic.sqlalchemy.org/)\n\n## Development\n\nThis project uses several tools to streamline the development process:\n\n### mise\n\nWe use [mise](https://mise.jdx.dev/) for managing project-level dependencies and environment variables. mise helps\nensure consistent development environments across different machines.\n\nTo get started with mise:\n\n1. Install mise by following the instructions on the [official website](https://mise.jdx.dev/).\n2. Run `mise install` in the project root to set up the development environment.\n\n### Poetry\n\n[Poetry](https://python-poetry.org/) is used for dependency management and packaging. It provides a clean,\nversion-controlled way to manage project dependencies.\n\nTo set up the project with Poetry:\n\n1. Install Poetry by following the instructions on the [official website](https://python-poetry.org/docs/#installation).\n2. Run `poetry install` to install project dependencies.\n\n### Jurigged for Live Reload\n\nWe use [Jurigged](https://github.com/breuleux/jurigged) for live code reloading during development. This allows you to\nsee changes in your code immediately without manually restarting the application.\n\nTo use Jurigged:\n\n1. Make sure you have installed the project dependencies using Poetry, including dev\n   dependencies `poetry install --with dev`.\n2. Run the bot with Jurigged:\n\n```bash\npoetry run jurigged -v -m src\n```\n\n## Internationalization (i18n)\n\n- We use [Plate](https://github.com/delivrance/plate) library to translate the bot's messages.\n- Translations are stored as JSON files in the `src/i18n/locales` directory, the default locale is `en_US`.\n- To add a new language, create a new JSON file in the `src/i18n/locales` directory, with the corresponding language\n  code,\n  translate the messages to that language.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyshalsager%2Ftelegram-feedback-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyshalsager%2Ftelegram-feedback-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyshalsager%2Ftelegram-feedback-bot/lists"}