{"id":20472622,"url":"https://github.com/the-earth/catbot","last_synced_at":"2026-05-31T22:31:08.013Z","repository":{"id":164470133,"uuid":"303694463","full_name":"The-Earth/catbot","owner":"The-Earth","description":"Telegram API wrapper","archived":false,"fork":false,"pushed_at":"2026-03-05T09:21:48.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-05T13:07:00.613Z","etag":null,"topics":["catbot","telegram-bot-api"],"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/The-Earth.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-10-13T12:23:20.000Z","updated_at":"2026-03-05T09:20:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"672ae744-5238-42a5-8869-fd5e3895a8d2","html_url":"https://github.com/The-Earth/catbot","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/The-Earth/catbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Earth%2Fcatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Earth%2Fcatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Earth%2Fcatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Earth%2Fcatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-Earth","download_url":"https://codeload.github.com/The-Earth/catbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-Earth%2Fcatbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33752286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"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":["catbot","telegram-bot-api"],"created_at":"2024-11-15T14:20:53.003Z","updated_at":"2026-05-31T22:31:08.001Z","avatar_url":"https://github.com/The-Earth.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# catbot\n\ncatbot is a multithread library for [Telegram](https://t.me) bot development. It provides a Python interface for [Telegram bot API](https://core.telegram.org/bots/api) and manages [update steam](https://core.telegram.org/bots/api#getting-updates) for bot developers. \n\n## Installation\n\nWe need Python 3.13+ and the latest [requests](https://github.com/psf/requests) to run our bots.\n\nFind `catbot-x.tar.gz` in [release](https://github.com/The-Earth/catbot/releases), download the latest version and install it by \n\n```shell\npip install catbot-x.tar.gz\n```\n\n## Quick start\n\nBy using catbot, a configuration json file is needed (or alternatively pass a dict to the initializer). Necessary configurations are bot token and proxy settings (see [example config](config_example.json)). If your bot does not use proxy to access Telegram server, simple set `proxy - enable` to `false`. Other configs could be helpful, such as a set of messages for auto-reply.\n\nLet's say your config file is `config.json`, then create a bot instance:\n\n```python\nimport catbot\n\nbot = catbot.Bot(config_path='config.json')\n```\n\nLet's start with auto-replying the `/start` command in private chat with users, which is the very beginning of interactions with users.\n\nFirst, create a criteria function to tell catbot if there is a need to create a new thread to deal with the received message. Only simple and fast jobs should be put in this function in order not to block the main thread. Move time-consuming tasks (database querying, web requests) into action functions, which are running in separate threads.\n\n```python\ndef start_cri(msg: catbot.Message) -\u003e bool:\n    return msg.chat.type == 'private' and msg.text == '/start'\n```\n\nThis function checks whether the message is from a private chat and its content is exactly `/start`. Then we need an action function.\n\n```python\n@bot.msg_task(start_cri)\ndef start(msg: catbot.Message):\n    bot.send_message(chat_id=msg.chat.id, text='Hello')\n```\n\nThis function send a `Hello` to the chat it received a `/start` from. The `msg_task` from `bot` adds both two functions to the task list of the bot. Notice that this task responds to [Message](https://core.telegram.org/bots/api#message) objects (also, `Message` class in catbot). So we use `msg_task` decorator here. (For other types of incoming events, catbot supports [CallbackQuery](https://core.telegram.org/bots/api#callbackquery) and [ChatMemberUpdated](https://core.telegram.org/bots/api#chatmemberupdated), with `query_task` and `member_status_task`, respectively.)\n\nAnd start the bot:\n\n```python\nwith bot:\n    bot.start()\n```\n\ncatbot contains context management to save changed configurations and data on exit.\n\n## Go further\n\nMost methods of the `Bot` class (actions of a bot) have their inline documents. Generally, arguments of the methods are just the same or very similar to what [Telegram bot API](https://core.telegram.org/bots/api) says. If your desired method is not supported by catbot yet, catbot provides support for raw api call by `bot.api(action: str, data: dict)`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-earth%2Fcatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-earth%2Fcatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-earth%2Fcatbot/lists"}