TelegramBotAPI Documentation

The TelegramBotAPI ecosystem is split into several modules to allow for granular dependency management:

• TelegramBotAPI Core: The fundamental library components.
• TelegramBotAPI API: Extensions for interacting with the API.
• TelegramBotAPI Utils: Utility functions and helpers.
• TelegramBotAPI Behaviour Builder: A framework for building bot behaviors.
• TelegramBotAPI Behaviour Builder FSM: Finite State Machine (FSM) support for the Behaviour Builder.

The tgbotapi.api library replaces the generic bot.execute(Request) pattern from tgbotapi.core with direct, named method calls that match Telegram's API terminology. This makes the code more readable and provides clearer signatures.

By default, the FSM uses a standard storage mechanism. If you need to use a custom store for managing states (steps), you can:

1. Extend the StatesManager class.
2. Use DefaultStatesManager configured with a custom DefaultStatesManagerRepo.

Triggers are mechanisms that listen for incoming messages. They can include filters for specific message types and filters for the context used in sub-contexts.

For example, onText allows you to specify:

• includeFilterByChatInBehaviourSubContext: If true, the sub-context will be filtered by the chat ID of the incoming message. If false, the sub-context receives all messages.
• additionalFilter: A lambda to validate the incoming message before it reaches the main handler.

The main lambda receives a BehaviourContext (e.g., TextMessage).

telegramBotWithBehaviour(TOKEN) {
    onText(
        includeFilterByChatInBehaviourSubContext = true,
        additionalFilter = { message: TextMessage ->
            // check requirements here
        }
    ) { message: TextMessage -> 
        // actions and waiters go here
    }
}

The library provides two distinct modes for local exception handling:

1. safely: Used when you want to retrieve a value or throw an exception. If the error handler block is skipped or doesn't handle the error, it will throw an exception by default.
2. safelyWithoutExceptions: Similar to safely, but instead of throwing an exception when something goes wrong, it returns a nullable result type (e.g., T?).

// Example of 'safely' returning a specific type
safely(
    {
        it.printStackTrace()
        "error"
    }
) {
    error("Hi :)") // emulate exception throwing
    "ok"
} // result will be with type String

// Example of 'safelyWithoutExceptions' returning nullable
safelyWithouExceptions {
    // do something
} // will returns nullable result type

To define a catch-all exception handler for your entire bot logic, provide a defaultExceptionsHandler lambda when building your bot's behavior. This handler is applied to the CoroutineContext of the provided scope. The library uses ContextSafelyExceptionHandler internally to ensure your custom handler is called when exceptions occur within your bot logic.

val bot = telegramBot("TOKEN")

bot.buildBehaviour (
    scope = scope,
    defaultExceptionsHandler = {
        it.printStackTrace()
    }
) {
    // ...
}

Alternatively, use telegramBotWithBehaviour:

val bot = telegramBotWithBehaviour (
    "TOKEN",
    scope = scope,
    defaultExceptionsHandler = {
        it.printStackTrace()
    }
) {
    // ...
}

Long Polling is the simplest way to retrieve updates. You can use several extension functions depending on whether you want to pass a pre-created filter or a lambda.

It is highly recommended to pass a CoroutineScope to manage the lifecycle of updates effectively.

Using a pre-created filter:

val filter = FlowsUpdatesFilter(64)
bot.startGettingOfUpdatesByLongPolling(filter)

Using a lambda directly:

bot.startGettingOfUpdatesByLongPolling(
    { println("Received message update: $it") }
)

Using the startGettingFlowsUpdatesByLongPolling extension: This allows you to define the logic within a block where this refers to the filter:

bot.startGettingFlowsUpdatesByLongPolling(
    scope = CoroutineScope(Dispatchers.Default)
) {
    textMessages().onEach { println("I have received text message: ${it.content}") }.launchIn(this)
}

Add the following dependency to your pom.xml. Ensure you replace ${telegrambotapi.version} with the desired version number.

<dependency>
  <groupId>dev.inmo</groupId>
  <artifactId>tgbotapi.core</artifactId>
  <version>${telegrambotapi.version}</version>
</dependency>

The tgbotapi.behaviour_builder extension provides a high-level DSL to handle bot steps and routine message processing, replacing manual Flow subscriptions. Instead of manually subscribing to messagesFlow, you can use telegramBotWithBehaviour(token) to define logic based on commands or text patterns.

telegramBotWithBehaviour(token) {
    onCommand("start".regex) {
        execute(SendTextMessage(it.chat.id, "This bot can ..."))
    }
}

To process incoming updates, you can use a FlowsUpdatesFilter. This allows you to separate different types of updates (including media groups) and use Kotlin Flows to filter, map, and react to specific data.

Note: These features are part of the tgbotapi.utils dependency integration.

// 1. Create a filter
val filter = FlowsUpdatesFilter(100)

// 2. Start getting updates with a specific scope
bot.startGettingOfUpdates(
    filter,
    scope = CoroutineScope(Dispatchers.Default)
)

// 3. Use the filter's flows to process specific data
filter.messageFlow.mapNotNull {
    it.data as? ContentMessage<*>
}.onEach {
    println(it)
}.launchIn(
    CoroutineScope(Dispatchers.Default)
)