telegram-bot

User-friendly Telegram Bot API wrapper supporting long-polling and webhook modes, command and input handlers, and flexible configuration options. Offers asynchronous request handling and comprehensive response processing.

JVMKotlin/NativeJS
GitHub stars247
Authorsvendelieu
Open issues4
LicenseApache License 2.0
Creation datealmost 4 years ago

Last activityabout 19 hours ago
Latest release9.4.0 (18 days ago)

Telegram bot api library logo

Telegram Bot

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

Validate Gradle Wrapper

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.3.6"
    id("eu.vendeli.telegram-bot") version "9.4.0"
}
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.3.6"
}

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

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) {
    sendMessage { "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) {
    sendMessage { "Nice to meet you, ${update.text}" }.send(user, bot)
    sendMessage { "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 set functionality through dsl:

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

    bot.setFunctionality {
        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
        }
    }
    
    bot.handleUpdates()
}

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.

Also, you can check plugin configuration options.

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}")
}

All sendReturning methods 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.

For AI assistants

AI coding assistants: see AGENTS.md for project context and conventions.

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.

JVMKotlin/NativeJS
GitHub stars247
Authorsvendelieu
Open issues4
LicenseApache License 2.0
Creation datealmost 4 years ago

Last activityabout 19 hours ago
Latest release9.4.0 (18 days ago)

Telegram bot api library logo

Telegram Bot

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

Validate Gradle Wrapper

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.3.6"
    id("eu.vendeli.telegram-bot") version "9.4.0"
}
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.3.6"
}

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

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) {
    sendMessage { "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) {
    sendMessage { "Nice to meet you, ${update.text}" }.send(user, bot)
    sendMessage { "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 set functionality through dsl:

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

    bot.setFunctionality {
        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
        }
    }
    
    bot.handleUpdates()
}

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.

Also, you can check plugin configuration options.

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}")
}

All sendReturning methods 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.

For AI assistants

AI coding assistants: see AGENTS.md for project context and conventions.

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.