Telegram Bot

Telegram Bot Api wrapper with a user-friendly interface.

Installation

Add the library itself to the dependencies' module that you need it.

build.gradle.kts example:

dependencies {
    implementation("eu.vendeli:telegram-bot:3.4.0")
}

Or if you use a different builder, look in the installation article.

Samples

You can see the samples in the telegram-bot_template repository. In the basic branch itself there is an empty draft that can be used to create any bot you want.

there you can find in the appropriate branches:

Conversation - An example of using Inputs and storing data in UserData.
Echo - Echo bot :)
Exception-handling - Simple example of exception handling
Ktor-webhook - An example of using webhook with Ktor
Poll - An example of how to build a questionnaire bot.
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

Usage

suspend fun main() {
    val bot = TelegramBot("BOT_TOKEN", "com.example.controllers")
    /**
     * Second parameter is the package in which commands/inputs will be searched.
     */

    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.set(user) { "conversation" }
}

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

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

It is also possible to process updates manually:

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(user, bot)
            message { "What is your favorite food?" }.send(user, bot)
        }.breakIf({ message.text == "peanut butter" }) { // chain break condition
            message { "Oh, too bad, I'm allergic to it." }.send(user, bot)
            // action that will be applied when match
        }.andThen {
            // next input point if break condition doesn't match
        }
    }
}

There is also a wiki section which is updated frequently.

You are welcome to check it out :)

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.

Requests limiting

Library as well supports limiting requests from users:

// ...
val bot = TelegramBot("BOT_TOKEN") {
    rateLimiter { // general limits
        limits = RateLimits(period = 10000, rate = 5)
    }
}

// Limits on certain actions
@CommandHandler(["/start"], RateLimits(period = 1000L, rate = 1L)) // or InputHandler
suspend fun start(user: User, bot: TelegramBot) {
    // ...
}
// In manual mode
onCommand("/start", RateLimits(period = 1000L, rate = 1L)) {
    // ...
}
// ...

Processing responses

if you want to operate with response you can use sendAsync() instead of send() method, which returns Response:

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

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

Questions

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

Sintexer/telegram-bot