https://github.com/dehuckakpyt/telegram-bot
Kotlin Telegram Bot Library for creating scalable and expandable applications with helpful features.
https://github.com/dehuckakpyt/telegram-bot
bot coroutines kotlin kotlin-bot kotlin-framework kotlin-library kotlin-telegram-bot ktor spring telegram telegram-bot telegram-bot-api telegram-bots
Last synced: about 2 months ago
JSON representation
Kotlin Telegram Bot Library for creating scalable and expandable applications with helpful features.
- Host: GitHub
- URL: https://github.com/dehuckakpyt/telegram-bot
- Owner: DEHuckaKpyT
- License: apache-2.0
- Created: 2023-07-26T02:21:03.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2026-04-02T13:03:11.000Z (2 months ago)
- Last Synced: 2026-04-02T20:26:58.962Z (2 months ago)
- Topics: bot, coroutines, kotlin, kotlin-bot, kotlin-framework, kotlin-library, kotlin-telegram-bot, ktor, spring, telegram, telegram-bot, telegram-bot-api, telegram-bots
- Language: Kotlin
- Homepage: https://dehuckakpyt.github.io/telegram-bot/starter-topic.html
- Size: 11.3 MB
- Stars: 47
- Watchers: 2
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Kotlin Telegram Bot
[](https://central.sonatype.com/artifact/io.github.dehuckakpyt.telegrambot/telegram-bot-core)
[](https://dehuckakpyt.github.io/telegram-bot/starter-topic.html)
[](https://t.me/+8YNQBUvqe-phMzYy)
[](https://core.telegram.org/bots/api)
[](https://github.com/DEHuckaKpyT/telegram-bot/blob/master/LICENSE.txt)
Kotlin library for creating Telegram Bots. You can use clean version, with implementation for [Spring](https://spring.io/), [Ktor](https://ktor.io/)+[Koin](https://insert-koin.io/) or create with you own implementation.
It have also possibility to save state in database with [Spring JPA](https://spring.io/projects/spring-data-jpa/) or [Exposed](https://github.com/JetBrains/Exposed).
[Full documentation with examples and explanations](https://dehuckakpyt.github.io/telegram-bot/starter-topic.html).
Example of applications in [example-spring](https://github.com/DEHuckaKpyT/telegram-bot/tree/master/example-spring), [example-ktor](https://github.com/DEHuckaKpyT/telegram-bot/tree/master/example-ktor), [example-core](https://github.com/DEHuckaKpyT/telegram-bot/tree/master/example-core) directories.
## Why this library
- Focused on building a **dialog with the user** (for example, no need to specify `chatId` in dialog chains).
- Has **many useful utilities** (such as templating, keyboard and button creating and other).
- Telegram API methods realization have **overloads** for more comfortable usage (like a `chatId` as `String` or `Long`).
- Working on **coroutines**.
- Has **clean** version or with **Spring** or **Ktor+Koin** frameworks.
- Has possibility to **save state in database** with **Spring JPA** or **Exposed**.
- Easy to **write tests** for your bot.
## Tested with
- JDK 17
- Kotlin 2.2.21
## Quick start
Token/username can be provided from code, `application.*` application config or `telegram-bot.yaml`.
`build.gradle.kts`
```kotlin
repositories {
mavenCentral()
}
dependencies {
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-core:$telegram_bot_version")
}
```
### Core version
Can be used for integrate with any frameworks manually.
`com/example/myproject/App.kt`
```kotlin
fun main(args: Array): Unit {
val config = TelegramBotConfig().apply {
// token/username can be loaded from resources/telegram-bot.yaml
// token = ""
// username = ""
receiving {
handling {
startCommand()
}
}
}
val context = TelegramBotFactory.createTelegramBotContext(config)
val updateReceiver = context.updateReceiver
// get telegramBot, templater, buttonFactory and other from created context...
// start and stop for example only, use this methods with starting and stopping your application
updateReceiver.start()
readlnOrNull()
updateReceiver.stop()
}
```
`resources/telegram-bot.yaml`
```yaml
telegram-bot.token: ${TELEGRAM_BOT_TOKEN}
telegram-bot.username: ${TELEGRAM_BOT_USERNAME}
```
`com/example/myproject/handler/StartHandler.kt`
```kotlin
fun BotHandling.startCommand() {
command("/start", next = "get_name") {
// you don't have to specify a chatId to send messages
sendMessage("Hello, my name is ${bot.username} :-)")
// but you can do it
bot.sendMessage(chatId, "And what is your name?")
}
step("get_name") {
sendMessage("Nice to meet you, $text!")
}
}
```
### Spring version
Ready-to-use solution for use with Spring.
`build.gradle.kts`
```kotlin
repositories {
mavenCentral()
}
dependencies {
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-core:$telegram_bot_version")
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-spring:$telegram_bot_version")
}
```
`com/example/myproject/config/BotConfig.kt`
```kotlin
@EnableTelegramBot
@Configuration
class BotConfig {
@Bean //optional bean
fun telegramBotConfig(): TelegramBotConfig = TelegramBotConfig().apply {
//configure..
}
}
```
`resources/application.properties`
```
telegram-bot.token=${TELEGRAM_BOT_TOKEN}
telegram-bot.username=${TELEGRAM_BOT_USERNAME}
```
`com/example/myproject/handler/StartHandler.kt`
```kotlin
@HandlerComponent
class StartHandler : BotHandler({
command("/start") {
sendMessage("Hello, my name is ${bot.username} :-)")
}
})
```
### Ktor+Koin version
Ready-to-use solution for use with Ktor+Koin.
`build.gradle.kts`
```kotlin
plugins {
// Optional plugin for koin
id("com.google.devtools.ksp") version "<>"
}
repositories {
mavenCentral()
}
dependencies {
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-core:$telegram_bot_version")
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-ktor:$telegram_bot_version")
// Optional dependencies for koin
compileOnly("io.insert-koin:koin-annotations:<>")
ksp("io.insert-koin:koin-ksp-compiler:<>")
}
ksp {
arg("KOIN_DEFAULT_MODULE", "true")
}
```
`com/example/myproject/KtorApp.kt`
```kotlin
fun Application.module() {
install(Koin) {
modules(defaultModule)
}
install(TelegramBot) {
//configure..
}
}
```
`resources/application.conf`
```
telegram-bot {
token = ${TELEGRAM_BOT_TOKEN}
username = ${TELEGRAM_BOT_USERNAME}
}
```
`com/example/myproject/handler/StartHandler.kt`
```kotlin
@Factory
class StartHandler : BotHandler({
command("/start") {
sendMessage("Hello, my name is ${bot.username} :-)")
}
})
```
## Database integration
> [!WARNING]
> And it is highly recommended to use with saving states in database.
> There are ready-to-use solutions for Spring JPA and Exposed.
> Interfaces to be implemented with saving to the database described here.
### Spring JPA
All you have to do is add a dependency for `source-jpa`:
#### Spring 3.x
```kotlin
dependencies {
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-core:$telegram_bot_version")
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-spring:$telegram_bot_version")
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-source-jpa:$telegram_bot_version")
}
```
#### Available properties
| PROPERTY | DEFAULT | DESCRIPTION |
|------------------------------------------------------------|---------|----------------------------------------------------------------------|
| `telegram-bot.source-jpa.enabled` | `true` | Disable all default sources |
| `telegram-bot.source-jpa.message-source.enabled` | `true` | Disable default message source |
| `telegram-bot.source-jpa.chain-source.enabled` | `true` | Disable default chain source |
| `telegram-bot.source-jpa.callback-content-source.enabled` | `true` | Disable default callback content source |
| `telegram-bot.source-jpa.callback-content-source.per-user` | `20` | Max count of contents will be saved for every user (`-1` for ignore) |
### Exposed
To save the state in the database, it is necessary to connect to it using [Exposed](https://github.com/JetBrains/Exposed) ([example](https://github.com/DEHuckaKpyT/telegram-bot/blob/master/example/src/main/kotlin/io/github/dehuckakpyt/telegrambotexample/plugin/DatabaseConnection.kt)).
Then add the dependency and specify the sources:
```kotlin
dependencies {
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-core:$telegram_bot_version")
implementation("io.github.dehuckakpyt.telegrambot:telegram-bot-source-exposed:$telegram_bot_version")
}
```
```kotlin
val config = TelegramBotConfig().apply {
messageSource = { MessageSource.inDatabase }
receiving {
callbackContentSource = {
CallbackContentSource.inDatabase(
maxCallbackContentsPerUser = 20
)
}
chainSource = { ChainSource.inDatabase }
}
}
```
[🔗Full documentation with examples and explanations🔗](https://dehuckakpyt.github.io/telegram-bot/starter-topic.html).