README.md

Telegram Bot

Telegram Bot Api wrapper with a user-friendly interface.

Installation

Add the ksp plugin and library plugin to your Gradle build file.

build.gradle.kts example:

plugins {
    // ...
    id("com.google.devtools.ksp") version "2.1.0-1.0.29"
    id("eu.vendeli.telegram-bot") version "7.6.2"
}

Manually

To set up the project without using the plugin, you need to add a dependency and configure the ksp processor:

plugins {
    // ...
    id("com.google.devtools.ksp") version "2.1.0-1.0.29"
}

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

For multiplatform, you need to add the dependency to common sources and define ksp for the targets you need, see example in native-example.

Snapshots

To install snapshot versions, add snapshot repository, if you're using plugin just use addSnapshotRepo parameter:

ktGram {
    forceVersion = "branch-xxxxxx~xxxxxx"
    addSnapshotRepo = true
}

or manually add repository:

repositories {
    mavenCentral()
    // ...
    maven("https://mvn.vendeli.eu/telegram-bot") // this
}

And add library dependency (with ksp processor) as described in manually section using the latest package version from packages or from badge above.

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.
• GatekeeperBot - Gatekeeper bot.
• 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 there are different options to configure through external sources.

You can read more in a Bot configuration article.

Processing responses

To process over response or/and have more control over request flow use sendReturning() instead of send() method, which returns Response:

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

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

Additional resources

• There is a wiki section that has helpful information.
• API reference

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.