{"id":18238312,"url":"https://github.com/gersonfreire/telegram_framework_bolt","last_synced_at":"2025-04-11T12:14:37.433Z","repository":{"id":259617101,"uuid":"877612982","full_name":"gersonfreire/telegram_framework_bolt","owner":"gersonfreire","description":"A powerful and extensible Python-based Telegram bot framework","archived":false,"fork":false,"pushed_at":"2024-12-08T23:19:06.000Z","size":335,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T20:38:24.516Z","etag":null,"topics":["chatbot","framework","python","python-telegram-bot","python3","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"https://github.com/gersonfreire/telegram-bot-framework","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/gersonfreire.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"gersonfaf61","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-10-23T23:52:42.000Z","updated_at":"2024-12-08T16:29:11.000Z","dependencies_parsed_at":"2024-10-26T23:06:32.095Z","dependency_job_id":"da46c1fb-fd0c-4f4e-b8a8-8be5b7eed24f","html_url":"https://github.com/gersonfreire/telegram_framework_bolt","commit_stats":null,"previous_names":["gersonfreire/telegram_framework_bolt"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gersonfreire%2Ftelegram_framework_bolt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gersonfreire%2Ftelegram_framework_bolt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gersonfreire%2Ftelegram_framework_bolt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gersonfreire%2Ftelegram_framework_bolt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gersonfreire","download_url":"https://codeload.github.com/gersonfreire/telegram_framework_bolt/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248399099,"owners_count":21097295,"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":["chatbot","framework","python","python-telegram-bot","python3","telegram","telegram-bot"],"created_at":"2024-11-05T03:05:00.737Z","updated_at":"2025-04-11T12:14:37.404Z","avatar_url":"https://github.com/gersonfreire.png","language":"Python","funding_links":["https://github.com/sponsors/gersonfaf61"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"\" rel=\"noopener\"\u003e\n \u003cimg width=200px height=200px src=\"https://i.imgur.com/FxL5qM0.jpg\" alt=\"Bot logo\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Telegram Bot Framework\n\nA powerful and extensible Python-based Telegram bot framework that provides automatic command handling, settings management, and easy configuration.\n\nThis is an updated and totally rewritten from ground of a [legacy version](https://github.com/gersonfreire/telegram-bot-framework)\n\n## About\n\nYou can find many libraries and modules ready to build bots on Telegram, but none of them cover the basic functionalities that are almost indispensable, such as creating a help menu automatically from commands, registering users, generating a log in the Telegram administrator and others. The purpose of this library is to fill these gaps and allow Telegram bot developers to quickly create powerful, stable and secure bots in just a few lines of code. This work is still in its early stages, but I invite you to help me explore and conquer the fascinating world of Telegram bots by collaborating and using this library.\n\nThe orginal article in English is here: [A Python Framework for Telegram Bots - DEV Community](https://dev.to/gersonfreire/a-python-framework-for-telegram-bots-238f)\n\nThe orginal article in Portuguese is here: [Biblioteca em nível de aplicação para criar bots no Telegram 🤖 · telegram · TabNews](https://www.tabnews.com.br/telegram/biblioteca-de-nivel-de-aplicativo-para-criar-bots-no-telegram)\n\n## How it works\n\nBasically, we build a class called *TelegramBotFramework*, which inherits from the *python-telegram-bot Application class*, implemented by the telegram.ext library, provided by the python-telegram-bot package, version 21 or greater ([https://github.com/python-telegram-bot/python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)). In this child class, we implement some default methods to handle the universal commands /start, /help and other unrecognized commands. However, the developer can implement their own command handlers without losing the built-in functionality. I recommend reading the source code for more details. I also recommend Python 3.12 version.\n\n## Features\n\n- 🚀 Automatic command handling\n- ⚙️ Built-in settings management\n- 📝 YAML-based configuration\n- 🔒 Environment variable support\n- 📚 Easy to extend and customize\n\n## Setup\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/yourusername/telegram-bot-framework.git\ncd telegram-bot-framework\n```\n\n2. Create and activate a virtual environment:\n\n```bash\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n```\n\n3. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n4. Configure the bot:\n\n   - Copy `.env.example` to `.env` and add your bot token\n   - Copy `config.yml.example` to `config.yml` and customize as needed\n5. Run the bot:\n\n```bash\npython main.py\n```\n\n## Importing\n\n```python\nfrom bot.core import TelegramBotFramework\nfrom bot.handlers import CommandHandler\nfrom bot.settings import Settings\n```\n\n## Project Structure\n\n```\n├── src/\n│   ├── bot/\n│   │   ├── __init__.py\n│   │   ├── core.py\n│   │   ├── handlers.py\n│   │   └── settings.py\n│   └── main.py\n├── .env.example\n├── .gitignore\n├── config.yml.example\n├── requirements.txt\n└── README.md\n```\n\n## Configuration\n\n Environment Variables\n\nCreate a `.env` file in the root directory and add your bot token and admin user IDs:\n\n```\nDEFAULT_BOT_TOKEN=your_bot_token_here\nADMIN_ID_LIST=your_telegram_user_id_here\n```\n\n### Config File (config.yml)\n\nThe `config.yml` file contains bot settings and command configurations:\n\n```yaml\nbot:\n  name: \"MyTelegramBot\"\n  commands:\n    start:\n      description: \"Start the bot\"\n      response: \"Welcome message\"\n    help:\n      description: \"Show available commands\"\n      response: \"Available commands:\\n{commands}\"\n    settings:\n      description: \"Manage bot settings\"\n      response: \"Current Settings:\\n{settings}\"\n    echo:\n      description: \"Echo the user's message\"\n      response: \"{message}\"\n    stop:\n      description: \"Stop the bot\"\n      response: \"Bot stopped.\"\n    version:\n      description: \"Show bot version\"\n      response: \"Bot version: {version}\"\n    toggle_status:\n      description: \"Toggle status message\"\n      response: \"Status message toggled.\"\n    change_status_interval:\n      description: \"Change status message interval\"\n      response: \"Status message interval changed.\"\n    call_function:\n      description: \"Call a function\"\n      response: \"Function called.\"\n```\n\n## Available Commands\n\n- `/start` - Initialize the bot\n- `/help` - Display available commands\n- `/settings` - Show current bot settings\n- `/echo` - Echo the user's message\n- `/stop` - Stop the bot\n- `/version` - Show bot version\n- `/toggle_status` - Toggle status message\n- `/change_status_interval` - Change status message interval\n- `/call_function` - Call a function\n\n* `/eval` - Evaluate a Python expression `(`*new*)\n* `/exec` - Execute Python code `(`*new*)\n\n## Extending the Framework\n\nTo add new commands, update the `config.yml` file or use the `register_command` method:\n\n```python\nbot.register_command(\n    name=\"custom\",\n    description=\"A custom command\",\n    response=\"Custom response\"\n)\n```\n\n## Examples\n\nIn folder ` src\\examples` there is a couple of examples which is under construction like this framework, but the `host_watch_bot.py `sample is becoming interesting.\n\nThis bot provides a powerful way to monitor hosts and manage various tasks through Telegram. Make sure to familiarize yourself with the commands and their usage to get the most out of your experience!\n\nFor further assistance, refer to the [bot usage guide](src/examples/bot_usage.md) for more detailed information about the bot's features and setup.\n\n## License\n\nMIT License\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## Deploy library to *Pypi* (Optional)\n\n* If you do not have setuptools library already installed, you must run this command in order to create the distribution package using *setup.py*:\n\n```bash\npip install setuptools\n```\n\n* Additionally, if you do not have the *twine* tool, you will need to install it because it is the tool that uploads your package to *Pypi*:\n\n```bash\npip install twine\n```\n\n* Now, if already have *setuptools* installed, generate the package, check the version and other desired details on *setup.py* file and execute the following command to create the distribution folder locally:\n\n```bash\npython setup.py sdist bdist_wheel\n```\n\n* Finally, upload the distribution package to *Pypi* with the following command, which will ask for the *Pypi* API token:\n\n```bash\ntwine upload dist/*\n```\n\n* After deployed, your library can be installed anywhere with command, where `\u003clibrary-name\u003e` is the name set on setup.py:\n\n```bash\npip install \u003clibrary-name\u003e\n```\n\n## TODOS:\n\n* [X] Embed persistence to the bot framework\n* [X] Embed the settings into the bot framework\n* [ ] Set a crown at the help commands list to show which commands are admins'\n* [ ] Add a method to change settings\n* [ ] Add a command to display the settings\n* [ ] Add a command to stop the bot\n* [ ] Embed the logging into the bot framework\n* [ ] Add type hints to the class methods\n* [ ] Add docstrings to the class methods\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgersonfreire%2Ftelegram_framework_bolt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgersonfreire%2Ftelegram_framework_bolt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgersonfreire%2Ftelegram_framework_bolt/lists"}