Telegram Bot

Telegram Bot Api wrapper with a user-friendly interface.

Installation

Add the ksp plugin and library to the dependencies.

build.gradle.kts example:

plugins {
    // ...
    id("com.google.devtools.ksp") version "2.0.0-1.0.23"
}

dependencies {
    // ...
    implementation("eu.vendeli:telegram-bot:6.3.1")
    ksp("eu.vendeli:ksp:6.3.1")
}

Samples

Template repository - draft example.
FeedbackBot - Use ready example of a feedback bot.
Conversation - An example of using FSM and usage of BotContext.
Echo - Echo bot :)
Poll - An example of how to build a questionnaire bot.
Ktor webhook starter - An example of using webhook mode with Ktor.
Spring Boot usage - An example of using the bot organically in the Spring ecosystem, using its built-in DI.
Heroku ready example - An example of a bot working via Heroku.
Native example - An example of using a bot with Kotlin Native target.
Web app - Example of a bot using Telegram Webapps.

Usage

suspend fun main() {
    val bot = TelegramBot("BOT_TOKEN")

    bot.handleUpdates()
    // start long-polling listener
}

@CommandHandler(["/start"])
suspend fun start(user: User, bot: TelegramBot) {
    message { "Hello, what's your name?" }.send(user, bot)
    bot.inputListener[user] = "conversation"
}

@InputHandler(["conversation"], guard = UserPresentGuard::class)
suspend fun startConversation(update: ProcessedUpdate, user: User, bot: TelegramBot) {
    message { "Nice to meet you, ${update.text}" }.send(user, bot)
    message { "What is your favorite food?" }.send(user, bot)
    bot.inputListener.set(user) { "conversation-2step" } // another way to set input
}

@CommonHandler.Regex("blue colo?r")
suspend fun color(user: User, bot: TelegramBot) {
    message { "Oh you also like blue color?" }.send(user, bot)
}
//..

a little more detailed about handlers you can see in handlers article.

It is also possible to process updates functionally:

fun main() = runBlocking {
    val bot = TelegramBot("BOT_TOKEN")

    bot.handleUpdates { update ->
        onCommand("/start") {
            message { "Hello, what's your name?" }.send(user, bot)
            bot.inputListener[user] = "conversation"
        }
        inputChain("conversation") {
            message { "Nice to meet you, ${message.text}" }.send(update.getUser(), bot)
            message { "What is your favorite food?" }.send(update.getUser(), bot)
        }.breakIf({ message.text == "peanut butter" }) { // chain break condition
            message { "Oh, too bad, I'm allergic to it." }.send(update.getUser(), bot)
            // action that will be applied when match
        }.andThen {
            // next input point if break condition doesn't match
        }
    }
}

Configuration

The library has very flexible customization options,
and the ability to configure from the environment variables out of the box is also provided.

You can read more in a Bot configuration article.

Processing responses

All requests are async but to operate with response and have more control over flow you need use sendAsync() instead of send() method, which returns Response:

message { "test" }.sendAsync(user, bot).onFailure {
    println("code: ${it.errorCode} description: ${it.description}")
}

Any sendAsync method returns a Response on which you can also use methods getOrNull() , isSuccess() , onFailure()

Additional resources

There is a wiki section that have helpful information.

Questions

You're always welcome in our chat, feel free to ask.

Acknowledgements

A big thank you to everyone who has contributed to this project. Your support and feedback are invaluable.

If you find this library useful, please consider giving it a star. Your support helps us continue to improve and maintain this project.

vendelieu / telegram-bot