{"id":13826687,"url":"https://github.com/mevellea/telegram_menu","last_synced_at":"2025-07-09T01:31:03.999Z","repository":{"id":37037709,"uuid":"244030104","full_name":"mevellea/telegram_menu","owner":"mevellea","description":"A python library to generate navigation menus using Telegram Bot API","archived":false,"fork":false,"pushed_at":"2023-09-14T18:31:24.000Z","size":5586,"stargazers_count":98,"open_issues_count":0,"forks_count":24,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-31T11:39:22.318Z","etag":null,"topics":["python","telegram-bot","telegram-bot-api","telegram-menu"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mevellea.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":"2020-02-29T19:37:42.000Z","updated_at":"2024-08-20T07:13:39.000Z","dependencies_parsed_at":"2024-06-21T14:28:19.204Z","dependency_job_id":"17341890-bd2b-4a7e-b78d-9f5530d75c32","html_url":"https://github.com/mevellea/telegram_menu","commit_stats":{"total_commits":89,"total_committers":8,"mean_commits":11.125,"dds":0.6067415730337078,"last_synced_commit":"d85725bfa4466704b5a914b7eb11af105d473b1c"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevellea%2Ftelegram_menu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevellea%2Ftelegram_menu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevellea%2Ftelegram_menu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevellea%2Ftelegram_menu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mevellea","download_url":"https://codeload.github.com/mevellea/telegram_menu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225476383,"owners_count":17480215,"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","telegram-bot","telegram-bot-api","telegram-menu"],"created_at":"2024-08-04T09:01:42.586Z","updated_at":"2024-11-20T05:31:00.022Z","avatar_url":"https://github.com/mevellea.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# telegram_menu package\n\n\u003cimg src=\"https://img.shields.io/badge/python-3.8-blue.svg\" alt=\"drawing\"/\u003e \u003cimg src=\"https://img.shields.io/badge/python-3.11-blue.svg\" alt=\"drawing\"/\u003e\n\u003cbr/\u003e\nA python library to generate navigation menus using Telegram Bot API.\n\nFeatures:\n\n* Menu navigation using tree structure, unlimited depth\n* Support for sending pictures (local file or url), stickers, notifications, webapps and polls\n* Session manager with multiple users connecting to the same bot\n* Messages can read text input from the keyboard\n* Automatic deletion of messages when configurable timer has expired\n* Integration of HTML formatting + emojis\n\n\u003e **_[2023-01] NOTE:_** asyncio support was added in version 2.0.0. Previous versions use the oldest non-asynchronous version of python-telegram-bot and are not compatible.\n\nHere is an example of navigation with menus and inlined buttons:\n\n![Demo: TelegramMenuSession]  \n\n## Installation\n\n```bash\npip install telegram_menu\n```\n\n## Getting Started\n\nYou first need to [create a Telegram bot], then you can refer to the sample code in ``tests\\test_connection.py`` to run a complete use-case.\n\nA session can be started with the keyword ``/start`` from a Telegram client.\n\nFollowing code block creates a ``Hello, World!`` message:\n\n```python\nfrom telegram_menu import BaseMessage, TelegramMenuSession, NavigationHandler\n\nAPI_KEY = \"put_your_telegram_bot_api_key_here\"\n\nclass StartMessage(BaseMessage):\n    \"\"\"Start menu, create all app sub-menus.\"\"\"\n\n    LABEL = \"start\"\n\n    def __init__(self, navigation: NavigationHandler) -\u003e None:\n        \"\"\"Init StartMessage class.\"\"\"\n        super().__init__(navigation, StartMessage.LABEL)\n\n    def update(self) -\u003e str:\n        \"\"\"Update message content.\"\"\"\n        return \"Hello, world!\"\n\nTelegramMenuSession(API_KEY).start(StartMessage)\n```\n\nYou can add new buttons in ``StartMessage``, using ``self.add_button()`` method. \nThe callback of a button can be used to update the content of the current message, or to open a new menu.\nFor example, adding these lines in the constructor of the previous class will open a second menu:\n\n```python\nsecond_menu = SecondMenuMessage(navigation)\nself.add_button(label=\"Second menu\", callback=second_menu)\n```\n\nThen define the second message:\n\n```python\nclass SecondMenuMessage(BaseMessage):\n    \"\"\"Second menu, create an inlined button.\"\"\"\n\n    LABEL = \"action\"\n\n    def __init__(self, navigation: NavigationHandler) -\u003e None:\n        \"\"\"Init SecondMenuMessage class.\"\"\"\n        super().__init__(navigation, StartMessage.LABEL, inlined=True)\n\n        # 'run_and_notify' function executes an action and return a string as Telegram notification.\n        self.add_button(label=\"Action\", callback=self.run_and_notify)\n        # 'back' button goes back to previous menu\n        self.add_button_back()\n        # 'home' button goes back to main menu\n        self.add_button_home()\n\n    def update(self) -\u003e str:\n        \"\"\"Update message content.\"\"\"\n        # emoji can be inserted with a keyword enclosed with ::\n        # list of emojis can be found at this link: https://www.webfx.com/tools/emoji-cheat-sheet/\n        return \":warning: Second message\"\n\n    @staticmethod\n    def run_and_notify() -\u003e str:\n        \"\"\"Update message content.\"\"\"\n        return \"This is a notification\"\n```\n\nAn application message can contain several inlined buttons, the behavior is similar to MenuMessage buttons.\nTo define a message as inlined, the property ``inlined`` must be set to ``True``.\n\nA message can also be used to create a poll or show a picture, using property ``btype``.\n\nThe input field can be set using the property ``input_field`` (non-inlined messages only). You can use the keyword ``\u003cdisable\u003e`` to restore the default behaviour. \n\nThe default number of buttons per row is 2 for base keyboards, 4 for inlined keyboards, \nto create a new row the property ``new_row`` can be set to ``True`` when calling ``add_button()``.\n\n```python\nfrom telegram_menu import MenuButton\n\n# 'get_content' function must return the text content to display, eventually with Markdown formatting\nself.add_button(label=\"Display content\", callback=self.get_content, btype=ButtonType.MESSAGE)\n\n# 'get_picture' function must return the path of a picture to display in Telegram\nself.add_button(label=\"Show picture\", callback=self.get_picture, btype=ButtonType.PICTURE, new_row=True)\n\n# 'get_sticker' function must return the path of a sticker to display in Telegram\nself.add_button(label=\"Show sticker\", callback=self.get_sticker, btype=ButtonType.STICKER)\n\n# 'webapp_cb' function will receive the result of the given web-app\nwebapp_url = \"https://python-telegram-bot.org/static/webappbot\"\nself.add_button(label=\"Show picture\", callback=self.webapp_cb, web_app_url=webapp_url)\n\n# New buttons can be added to the 'keyboard' property of the message instance too.\n# Next poll message will get items to display from function 'get_playlists_arg', and run 'select_playlist' when \n# the poll button is selected, identified with emoji 'closed_book'\npoll_button = MenuButton(\n    label=\":closed_book:\", callback=self.select_playlist, btype=ButtonType.POLL, args=self.get_playlists_arg()\n)\nself.keyboard.append([poll_button])\n```\n\n## Structure\n\nClasses in package ``telegram_menu`` are stored in 2 python files:\n\n\n* [navigation.py] - Main interface, menu and message generation and management\n* [models.py] - Menu and message models, classes definition\n\n\u003cimg src=\"https://raw.githubusercontent.com/mevellea/telegram_menu/master/resources/packages.png\" width=\"400\"/\u003e\n\nFollowing class diagram describes all public interfaces:\n\n\u003cimg src=\"https://raw.githubusercontent.com/mevellea/telegram_menu/master/resources/classes.png\" width=\"800\"/\u003e\n\n[navigation.py]: https://github.com/mevellea/telegram_menu/blob/master/telegram_menu/navigation.py\n[models.py]: https://github.com/mevellea/telegram_menu/blob/master/telegram_menu/models.py\n[create a Telegram bot]: https://github.com/python-telegram-bot/python-telegram-bot/wiki/Introduction-to-the-API\n[Demo: TelegramMenuSession]: https://raw.githubusercontent.com/mevellea/telegram_menu/master/resources/demo.gif\n\n## Unit-tests\n\nTo execute the test suite, run the following command and then start a session from a Telegram client with the keyword **/start**.\n\n```bash\npython -m unittest\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmevellea%2Ftelegram_menu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmevellea%2Ftelegram_menu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmevellea%2Ftelegram_menu/lists"}