Skip to content

vendelieu/telegram-bot

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Telegram bot api library logo

Telegram Bot

Maven Central Supported version
KDocs codecov
Chat in Telegram Chat in Telegram

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.0.21-1.0.26"
    id("eu.vendeli.telegram-bot") version "7.4.1"
}
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.0.21-1.0.26"
}

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

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

Snapshot version

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

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

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.