{"id":47673338,"url":"https://github.com/bezsahara/telegramkitty","last_synced_at":"2026-04-27T04:01:02.695Z","repository":{"id":254505176,"uuid":"846146531","full_name":"bezsahara/TelegramKitty","owner":"bezsahara","description":"Powerful and type-safe Telegram Bot API wrapper with built-in cat pic functionality.","archived":false,"fork":false,"pushed_at":"2026-04-25T00:54:57.000Z","size":1107,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-25T02:40:33.475Z","etag":null,"topics":["kotlin","telegram-bot-api","vertx"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","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/bezsahara.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":"2024-08-22T16:10:22.000Z","updated_at":"2026-04-25T00:55:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"79fe3b98-0c90-4959-b978-5ecf5bece46a","html_url":"https://github.com/bezsahara/TelegramKitty","commit_stats":null,"previous_names":["bezsahara/telegramkitty"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/bezsahara/TelegramKitty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bezsahara%2FTelegramKitty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bezsahara%2FTelegramKitty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bezsahara%2FTelegramKitty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bezsahara%2FTelegramKitty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bezsahara","download_url":"https://codeload.github.com/bezsahara/TelegramKitty/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bezsahara%2FTelegramKitty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32321940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"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":["kotlin","telegram-bot-api","vertx"],"created_at":"2026-04-02T13:07:04.330Z","updated_at":"2026-04-27T04:01:02.688Z","avatar_url":"https://github.com/bezsahara.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![logo](logo.png)\n\n# TelegramKitty\nTelegramKitty is a Kotlin-first Telegram Bot API wrapper for fast JVM bots.\nIt gives you generated Telegram methods and models, a coroutine-friendly handler DSL,\npredictable update processing, and a pluggable HTTP layer.\n\nCurrent generated API target: **Telegram Bot API 9.6**.\n\nAnd yes, it can send [cat pictures](#cats).\n\nProject layout:\n\n- `kittybot` - generated Telegram API, core bot logic, dispatcher DSL, custom client SPI\n- `kittybot-client` - default Vert.x HTTP client, file helpers, and cat helpers\n- `samples` - runnable examples\n\n## Features\n\n- Generated Telegram Bot API methods and serializable Telegram types with official docs in KDoc\n- Simple polling and webhook setup\n- Handler DSL for commands, text, callback queries, contacts, media groups, and raw update types\n- Conversation API for interactive multi-step flows\n- `flowHandler`, routing, command groups, dynamic handlers, filters, guards, and context attributes\n- Single-thread, ordered multi-thread, and custom update processing\n- Allowed-update filtering and stale-update skipping with `ensureOnlyNewUpdates(...)`\n- Inline keyboard, reply keyboard, bot command, and message entity builders\n- File download helpers when using the default Vert.x client\n- Custom HTTP clients through `CustomClient`, with Ktor and Java `HttpClient` implementations available\n- Built-in cat helpers via `sendCatPicture(...)`, `sendTheCatApi(...)`, `sendHttpCat(...)`, and `sendTextCat()`\n\n## Installation\n\nUse the default Vert.x client:\n\n```kotlin\ndependencies {\n    implementation(\"org.bezsahara:kittybot:3.1.0\")\n    implementation(\"org.bezsahara:kittybot-client:3.1.0\")\n}\n```\n\nIf you want to provide your own HTTP client, `kittybot-client` is not required:\n\n```kotlin\ndependencies {\n    implementation(\"org.bezsahara:kittybot:3.1.0\")\n}\n```\n\n## Quick Start\n\n```kotlin\nval bot = KittyBot\u003cPollingReceiver\u003e {\n    token = System.getenv(\"BOT_TOKEN\")\n    ensureOnlyNewUpdates()\n\n    dispatchers {\n        command(\"/start\") {\n            bot.sendMessage(chatId, \"Hi from TelegramKitty\")\n        }\n    }\n}\n\nbot.startPolling()\n```\n\n## Conversations\n\n```kotlin\nval bot = KittyBot\u003cPollingReceiver\u003e {\n    token = System.getenv(\"BOT_TOKEN\")\n    ensureOnlyNewUpdates()\n\n    dispatchers {\n        buildConversation {\n            onStartCommand {\n                bot.sendMessage(chatId, \"Hi! What's your name?\")\n                val name = receiveText().await()\n\n                bot.sendMessage(chatId, \"Send a picture, $name\")\n                val picture = receivePhotos().await()\n            }\n        }\n    }\n}\n\nbot.startPolling()\n```\n\n## Webhooks\n\n```kotlin\nval token = System.getenv(\"BOT_TOKEN\")\n\nval bot = KittyBot\u003cWebhookReceiver\u003e {\n    this.token = token\n\n    webhook(\n        url = \"https://example.com/telegram/$token\",\n        deletePreviousWebhook = true\n    )\n\n    dispatchers {\n        text(\"/start\") {\n            bot.sendMessage(chatId, \"Hi from webhook mode\")\n        }\n    }\n}\n\nbot.start()\n\n// Pass raw Telegram webhook payloads from your HTTP server:\n// bot.onUpdate(payload)\n```\n\n## Custom Clients\n\nUse `kittybot-client` for the default Vert.x transport. If you want another HTTP engine,\nuse `useCustomClient(...)` or set a full `ClientBuilder` through `apiClientBuilder`.\n\nJava's built-in `HttpClient` works without extra dependencies:\n\n```kotlin\nval bot = KittyBot\u003cPollingReceiver\u003e {\n    token = System.getenv(\"BOT_TOKEN\")\n    useCustomClient(JavaCustomClient.createDefault())\n}\n```\n\nKtor is also supported. Add your own Ktor client dependencies and engine:\n\n```kotlin\ndependencies {\n    implementation(\"org.bezsahara:kittybot:3.1.0\")\n    implementation(\"io.ktor:ktor-client-core:3.4.0\")\n    implementation(\"io.ktor:ktor-client-cio:3.4.0\")\n}\n```\n\n```kotlin\nval bot = KittyBot\u003cPollingReceiver\u003e {\n    token = System.getenv(\"BOT_TOKEN\")\n    useCustomClient(KtorCustomClient(HttpClient(CIO)))\n\n    dispatchers {\n        text(\"/start\") {\n            bot.sendMessage(chatId, \"Running on a custom client\")\n        }\n    }\n}\n```\n\nThe `CustomClient` SPI receives absolute Telegram method URLs, so implementations only need to send requests and return raw responses.\n\n## Update Processing\n\nThe default updater mode is `UpdaterMode.SingleThread`. You can also switch to:\n\n- `UpdaterMode.MultiThread(...)`\n- `UpdaterMode.Custom(...)`\n\nFor example:\n\n```kotlin\nupdaterMode = UpdaterMode.MultiThread(\n    MultiIdentity.OfAnyUserChatIdentity,\n    parallelism = 32\n)\n```\n\nThis lets different chats/users run in parallel while preserving order for the same identity.\n\n## Just The API Client\n\nIf you only need Telegram API calls without the handler system, use `createTelegramBot(...)`.\n\n```kotlin\nval bot = createTelegramBot(System.getenv(\"BOT_TOKEN\"))\nval me = bot.getMe().unwrap()\n```\n\n## Cats\n\nCat helpers live in [cats.kt](kittybot-client/src/main/kotlin/org/bezsahara/kittybot/bot/cats.kt) and are available when you use the default Vert.x client module.\n\n```kotlin\ntext(\"/cat\") {\n    bot.sendCatPicture(chatId)\n}\n\ntext(\"/cat_says\") {\n    bot.sendCatPicture(chatId, \"TelegramKitty\")\n}\n\ntext(\"/httpcat\") {\n    bot.sendHttpCat(chatId, 404)\n}\n```\n\n## More Examples\n\nSee [samples](samples/src/main/kotlin) for runnable examples:\n\n- [polling.kt](samples/src/main/kotlin/polling.kt) and [webhook.kt](samples/src/main/kotlin/webhook.kt)\n- [ConversationBuilder.kt](samples/src/main/kotlin/ConversationBuilder.kt)\n- [FlowExample.kt](samples/src/main/kotlin/FlowExample.kt)\n- [RoutingExample.kt](samples/src/main/kotlin/RoutingExample.kt)\n- [DynamicHandlersExample.kt](samples/src/main/kotlin/DynamicHandlersExample.kt)\n- [CommandGroupExample.kt](samples/src/main/kotlin/CommandGroupExample.kt)\n- [FilesExample.kt](samples/src/main/kotlin/FilesExample.kt)\n- [MediaGroupExample.kt](samples/src/main/kotlin/MediaGroupExample.kt)\n\nYou can also check out [KittyChat](https://github.com/bezsahara/KittyChat) project.\nIt uses this library for a simple AI telegram bot for conversations.\n\n# License\nCopyright 2026 Hlib Korol\n\nPermission is hereby granted, free of charge,\nto any person obtaining a copy of this software and\nassociated documentation files (the \"Software\"),\nto deal in the Software without restriction,\nincluding without limitation the rights to use, copy, modify,\nmerge, publish, distribute, sublicense, and/or\nsell copies of the Software, and to permit persons\nto whom the Software is furnished to do so, subject\nto the following conditions:\n\nThe above copyright notice and this permission notice\nshall be included in all copies or substantial portions\nof the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES\nOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR\nANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF\nCONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION\nWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbezsahara%2Ftelegramkitty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbezsahara%2Ftelegramkitty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbezsahara%2Ftelegramkitty/lists"}