Kotlin Telegram Bot: a typed wrapper with a dispatch DSL

A bot instance, and a dispatch block

Kotlin Telegram Bot is a wrapper for the Telegram Bot API written in Kotlin, and the README says creating a bot instance is really simple:

fun main() {
    val bot = bot {
        token = "YOUR_API_KEY"
    }
}

That is the whole setup, a builder with a token. The library is Apache-2.0 licensed, the primary language is Kotlin, and the last push to the main branch was on 2026-05-15, the same day as the 10.0.0 release.

Polling and routing is the second example, and this is where the library's shape becomes clear:

fun main() {
    val bot = bot {
        token = "YOUR_API_KEY"
        dispatch {
            text {
                bot.sendMessage(ChatId.fromId(message.chat.id), text = text)
            }
        }
    }
    bot.startPolling()
}

The dispatch block is a DSL, so the routing rules are nested scopes rather than a table of predicates. Inside the text block, message and text are in scope, which is why the sendMessage call reads as bot.sendMessage(ChatId.fromId(message.chat.id), text = text) with no receiver plumbing.

Commands work the same way:

fun main() {
    val bot = bot {
        token = "YOUR_API_KEY"
        dispatch {
            command("start") {
                val result = bot.sendMessage(chatId = ChatId.fromId(message.chat.id), text = "Hi there!")
                result.fold({
                    // do something here with the response
                },{
                    // do something with the error 
                })
            }
        }
    }
    bot.startPolling()
}

The fold call is the third thing worth noticing. A Telegram call returns a result object that is either a success or a failure, and you handle it by folding over the two cases, with the success branch first and the error branch second. That is a deliberate design choice, and it is the one that differs most from a typical HTTP wrapper.

The 6.x to 10.x jump, and what actually broke

The upgrading section is short and specific, and it is the thing to read before you bump the version.

The current line, 10.x, is up to date with Bot API 10.0 and includes the breaking changes Telegram introduced between 6.3 and 10.0. If you are coming from 6.2.0 or earlier, the README tells you to read docs/MIGRATION_10.md before bumping.

The summary of what changes is useful. Most code will keep compiling, but getChat now returns ChatFullInfo rather than Chat, the legacy reply, forward and preview parameters have richer replacements, and the duplicate entities.SuccessfulPayment was removed.

That first item is the one that catches people, because a return type change from a partial object to a fuller one is source compatible for a caller that reads properties but breaks a caller that declares the type, and a project with explicit types will fail to compile in a way that names the function rather than the problem.

The release history shows how the version numbering has tracked the API. The 10.0.0 tag is described as Bot API 6.3 to 10.0 catch-up, breaking, published on 2026-05-15. Before that came 6.3.0 on 2025-02-08 and 6.2.0 on 2024-08-09, so the library tracked the Telegram API and jumped from Bot API 6.3 to 10.0 in one release.

Installing it, and the JitPack coordinate

The download instructions are two build.gradle edits, and the first one is the part that catches people out.

repositories {
    maven { url "https://jitpack.io" }
}

The JitPack repository has to be added to the root build.gradle file, because the artifact is not on Maven Central. Then the dependency goes in the module's build.gradle file:

dependencies {
    implementation 'io.github.kotlin-telegram-bot.kotlin-telegram-bot:telegram:x.y.z'
}

The coordinate is unusual in two ways. The group is io.github.kotlin-telegram-bot.kotlin-telegram-bot, which is the JitPack convention of inverting the GitHub organisation and repository names, and the artifact is simply telegram. The version is x.y.z in the example, so you pin the one you want.

There is a release badge pointing at the JitPack build, and the CI badge points at a GitHub Actions workflow on the main branch.

The project also uses ktlint, with a badge for code style and a ktlint.gradle at the top level, and the contributing instructions make it part of the workflow. You fork and clone, run ./gradlew ktlintFormat, then run ./gradlew build to see whether the tests, ktlint and the abi checks pass, then commit, push and submit a pull request. The abi checks are the binary compatibility validator, which for a library at version 10 means an accidental change to a public signature is caught by the build rather than by a user's compiler.

The lineage from python-telegram-bot, and the Fuel techniques

The acknowledgements at the end of the README name two influences, and they explain the design of the library better than a feature list would.

The first is python-telegram-bot, the Python library, and the README says a big part of the architecture is inspired by it.

The second is Fuel, the Kotlin HTTP client library, and the README says some Kotlin techniques were taken from it.

Taken together, the two explain the shape of the whole library. The object model is Python Telegram Bot's, translated into Kotlin idioms by way of Fuel, and the DSL is what you get when a language with coroutines and scope functions is used to express a routing table.

The repository layout backs the same picture. There is a telegram/ directory for the library module, a samples/ directory with four projects, docs/ for the topic pages, a ktlint.gradle for the style rules, gradle.properties, settings.gradle, a.mailmap and.git-blame-ignore-revs for the history, and gradlew plus gradlew.bat for the build. The topics list hacktoberfest, kotlin, telegram, telegram-bot and telegram-bot-api, and the build badge and release badge sit at the top of the README.

The documentation map, and the newest parts of the API

The detailed documentation section is a list of topic pages, and reading the list tells you the current shape of the library.

The Core group covers getting updates, with polling, webhooks and allowed update types; webhooks, with a webhook { } DSL, a secretToken and manual processUpdate; error handling, with TelegramBotResult and telegramError { }; logging; and file uploads, with TelegramFile.ByFile, ByByteArray, ByInputStream, ByUrl and ByFileId.

The Chat and messages group covers Chat and ChatFullInfo and the 7.3 split, reply parameters for quoting and cross-chat replies, link preview options, forum topics including create, edit, close and delete, and reactions with set, delete and paid reactions.

The Built-in content group is polls, dice and games.

Then the newer areas. Telegram Stars and monetisation covers Telegram Stars with invoices, refunds and transactions, paid media with sendPaidMedia and purchases, and gifts for sending and managing. And Business bots covers business connection for connecting, sending on behalf and account management, plus stories with postStory, editStory, deleteStory and clickable areas.

The organisation of that list is a good indicator of which parts of the Bot API are settled and which are still moving. Core and chat and messages have dedicated pages per feature, while the newer money and business areas are grouped more broadly, which is roughly how the API documentation itself grew.

The samples folder has four projects, dispatcher/, echo/, polls/ and webhook/, and the README describes them as a simple echo bot, a more complex sample with commands, filters and a reply markup keyboard, a sample getting updates through a webhook using a Netty server, and an example bot sending polls and listening for poll answers.

Editorial conclusion

Adopt Kotlin Telegram Bot if you are writing a bot in Kotlin and want the API surface typed rather than hand-built JSON, because the dispatch DSL and the result type mean a failed call is a value you inspect rather than an exception you catch. Do not adopt it while you are on 6.x and planning an upgrade without reading docs/MIGRATION_10.md, since version 10 catches up Bot API 6.3 to 10.0 and changes getChat's return type. Before you start, note that the artifact is published through JitPack, so your build needs that repository added, and that the library is distributed with a binary compatibility validator in its own build.

Frequently asked questions

Official sources

1. Issues
2. kotlin-telegram-bot/kotlin-telegram-bot on GitHub
3. License: Apache-2.0
4. README
5. Releases