{"id":33185480,"url":"https://github.com/azhuchkov/tgbounce","last_synced_at":"2025-11-17T10:01:30.717Z","repository":{"id":207949364,"uuid":"720485006","full_name":"azhuchkov/tgbounce","owner":"azhuchkov","description":"Simple Telegram Assistant","archived":false,"fork":false,"pushed_at":"2024-05-09T17:51:47.000Z","size":90,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-09T19:09:22.977Z","etag":null,"topics":["assistant","automation","bot","linux","macos","messenger","python","telegram"],"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/azhuchkov.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}},"created_at":"2023-11-18T16:23:09.000Z","updated_at":"2024-05-09T17:51:51.000Z","dependencies_parsed_at":"2024-01-01T15:24:46.123Z","dependency_job_id":"d57010e7-f61b-4fd4-ac73-9af56fb70975","html_url":"https://github.com/azhuchkov/tgbounce","commit_stats":null,"previous_names":["azhuchkov/tgbounce"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/azhuchkov/tgbounce","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azhuchkov%2Ftgbounce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azhuchkov%2Ftgbounce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azhuchkov%2Ftgbounce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azhuchkov%2Ftgbounce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azhuchkov","download_url":"https://codeload.github.com/azhuchkov/tgbounce/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azhuchkov%2Ftgbounce/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284861038,"owners_count":27075155,"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-11-17T02:00:06.431Z","response_time":55,"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":["assistant","automation","bot","linux","macos","messenger","python","telegram"],"created_at":"2025-11-16T05:00:20.092Z","updated_at":"2025-11-17T10:01:30.711Z","avatar_url":"https://github.com/azhuchkov.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"chat\"\u003e\u003c/a\u003eChat and instant messaging"],"sub_categories":[],"readme":"# tgbounce: Your Telegram Assistant\n\u003cimg src=\"https://github.com/azhuchkov/tgbounce/blob/main/share/logo.png\" alt=\"logo\" align=\"right\"/\u003e\n\n**tgbounce** is an advanced [Telegram](https://telegram.org) assistant, crafted to automate your chat interactions. \nIt responds to messages, logs conversations, clicks buttons, and executes custom actions on your behalf, enhancing \nyour Telegram experience with seamless efficiency.\n\u003cbr clear=\"right\"/\u003e\n\n## Application Model\n`tgbounce` works with **bounces**, which are special rules set up to reply to messages. Each bounce has two parts: \n_conditions_ and _actions_. Conditions are the rules that decide when to do something, and actions are what `tgbounce`\ndoes when those conditions are met. To check if a condition is true, `tgbounce` uses _matchers_. These can be simple \nchecks or more complex evaluations. You can find out about the different kinds of fields `tgbounce` can work with \nby looking at the [Telegram documentation](https://core.telegram.org/tdlib/docs/classtd_1_1td__api_1_1message.html).\n\n### Available actions\nSpecify your reactions to messages with the following actions, which can be used in any combination:\n- **reply(text, receiver: int = None)**: Sends a reply, optionally to a different receiver.\n- **click(label)**: Clicks a button identified by its label.\n- **mark_as_read()**: Marks the message as read.\n- **exec(cmd)**: Executes a shell command, passing the message to the process' STDIN in JSON format.\n- **delete(revoke: bool = False)**: Deletes the message.\n\n## Examples\n\n### Automatic reply\nTo reply to any private message starting with \"Hello\", use this configuration:\n```json\n{\n  \"bounces\": [\n    {\n      \"on\": {\n        \"is_outgoing\": false,\n        \"is_private\": { \"value\":  \"chat_id \u003e= 0\", \"matcher\": \"expr\" },\n        \"content.text.text\": { \"value\": \"^Hello.*$\", \"matcher\": \"regexp\" }\n      },\n      \"do\": {\n        \"reply\": [\"Hi. Will respond to you in a minute.\"]\n      }\n    }\n  ]\n}\n\n```\n\n### Buttons handling\nTo click automatically on button \"Yes\" attached to special messages from a particular user, \nuse the following config:\n```json\n{\n  \"bounces\": [\n    {\n      \"on\": {\n        \"sender_id.user_id\": 1234567890, \n        \"content.text.text\": { \"value\": \"^Are you confirming .+?$\", \"matcher\": \"regexp\" }\n      },\n      \"do\": {\n        \"click\": [\"Yes\"],\n        \"mark_as_read\": []\n      }\n    }\n  ]\n}\n```\n\n### Command execution\nHere is the **bounce** that sends every text message to the [macOS Notification Center](https://support.apple.com/en-ge/guide/mac-help/mchl2fb1258f/14.0/mac/14.0):\n```json\n{\n  \"on\": {\n    \"is_outgoing\": false,\n    \"has_text\": {\n      \"value\": \"content.text != None and content.text.text != None\",\n      \"matcher\": \"expr\"\n    }\n  },\n  \"do\": {\n    \"exec\": [\"jq -r .content.text.text | terminal-notifier -title 'Telegram' -subtitle 'Incoming Message'\"]\n  }\n}\n```\n\n### Message deletion\nDelete forwarded messages from a particular user (for both participants):\n```json\n{\n  \"on\": {\n    \"sender_id.user_id\": 192830138,\n    \"is_forwarded\": { \"value\": \"forward_info != None\", \"matcher\": \"expr\" }\n  },\n  \"do\": {\n    \"delete\": {\"revoke\": true}\n  }\n}\n```\n\n## Installation\nFollow these steps to install tgbounce:\n\n1. Install the latest version using [Homebrew](https://brew.sh/): \n```console\n$ brew install azhuchkov/tools/tgbounce\n```\n\n2. Create a directory for configuration files and copy the example files into it:\n```console\n$ mkdir -m 0700 ~/.tgbounce/ \u0026\u0026 \\\n  install -b -m 0600 $(brew --prefix)/opt/tgbounce/share/{config.ini,bounces.json} ~/.tgbounce/\n```\n\n3. Edit the main configuration file:\n```console\n$ vim ~/.tgbounce/config.ini\n```\n\n4. Start tgbounce manually to enter the required credentials:\n```console\n$ $(brew --prefix)/opt/tgbounce/libexec/bin/python3 $(brew --prefix)/opt/tgbounce/libexec/tgbounce.py\n```\n\n5. After entering credentials, exit (`Ctrl+C`) and then start tgbounce as a service:\n```console\n$ brew services start tgbounce\n```\n\n## Troubleshooting\nIf you encounter issues, these commands can help:\n\n- Check the service status:\n```console\n$ brew services info tgbounce\n```\n\n- Access the logs:\n```console\n$ less $(brew --prefix)/var/log/tgbounce.log\n```\n\n- Reinstall the service, if any failures appear:\n```console\n$ brew uninstall tgbounce; brew install tgbounce; brew services restart tgbounce\n```\n\n## Signals\n`tgbounce` supports the following signals: `SIGUSR1`, `SIGHUP`. The latter is used to reload the bounces configuration, \nand the former is used to notify the process about network changes for faster catch-up.\n\n## License\n`tgbounce` is licensed under the [GPLv3 License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazhuchkov%2Ftgbounce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazhuchkov%2Ftgbounce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazhuchkov%2Ftgbounce/lists"}