https://github.com/vendelieu/telegram-bot
Telegram Bot API wrapper with handy Kotlin DSL.
https://github.com/vendelieu/telegram-bot
bot hacktoberfest kotlin telegram telegram-bot telegram-bot-api
Last synced: about 1 month ago
JSON representation
Telegram Bot API wrapper with handy Kotlin DSL.
- Host: GitHub
- URL: https://github.com/vendelieu/telegram-bot
- Owner: vendelieu
- License: apache-2.0
- Created: 2022-05-26T09:59:35.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-10-24T14:38:44.000Z (6 months ago)
- Last Synced: 2024-10-24T17:46:40.343Z (6 months ago)
- Topics: bot, hacktoberfest, kotlin, telegram, telegram-bot, telegram-bot-api
- Language: Kotlin
- Homepage: https://vendelieu.github.io/telegram-bot/
- Size: 63.3 MB
- Stars: 185
- Watchers: 3
- Forks: 14
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-kotlin-multiplatform - telegram-bot
- awesome-telegram - KtGram - Telegram Bot API wrapper with handy Kotlin DSL. (Bots / Bot Libs)
- awesome-telegram - Kotlin Telegram Bot
- awesome-telegram - Kotlin Telegram Bot
README
# Telegram Bot
[](https://search.maven.org/artifact/eu.vendeli/telegram-bot)
[](https://core.telegram.org/bots/api)\
[](https://vendelieu.github.io/telegram-bot/)
[](https://codecov.io/gh/vendelieu/telegram-bot) \
[](https://t.me/venny_tgbot)
[](https://t.me/kotlingram)
[](https://github.com/vendelieu/telegram-bot/actions/workflows/gradle-wrapper-validation.yml)
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:
```gradle
plugins {
// ...
id("com.google.devtools.ksp") version "2.1.10-1.0.29"
id("eu.vendeli.telegram-bot") version "7.9.0"
}
```
Manually
To set up the project without using the plugin, you need to add a dependency and configure the ksp processor:
```gradle
plugins {
// ...
id("com.google.devtools.ksp") version "2.1.10-1.0.29"
}
dependencies {
// ...
implementation("eu.vendeli:telegram-bot:7.9.0")
ksp("eu.vendeli:ksp:7.9.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](https://github.com/ktgram/native-example/blob/master/build.gradle.kts).
Snapshots
[](https://github.com/vendelieu?tab=packages&repo_name=telegram-bot)
To install snapshot versions, add snapshot repository,
if you're using plugin just use `addSnapshotRepo` parameter:
```gradle
ktGram {
forceVersion = "branch-xxxxxx~xxxxxx"
addSnapshotRepo = true
}
```
or manually add repository:
```gradle
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](https://github.com/vendelieu?tab=packages&repo_name=telegram-bot) or from badge above.
# Samples
- [Template repository](https://github.com/vendelieu/telegram-bot_template) - draft example.
- [FeedbackBot](https://github.com/ktgram/feedback-bot) - Use ready example of a feedback bot.
- [Conversation](https://github.com/vendelieu/telegram-bot_template/tree/conversation) - An example of using `FSM` and
usage of `BotContext`.
- [Echo](https://github.com/vendelieu/telegram-bot_template/tree/echo) - Echo bot :)
- [Poll](https://github.com/vendelieu/telegram-bot_template/tree/poll) - An example of how to build a questionnaire bot.
- [Ktor webhook starter](https://github.com/ktgram/webhook) - An example of using webhook mode
with Ktor.
- [Spring Boot usage](https://github.com/vendelieu/telegram-bot_template/tree/spring-bot) - An example of using the bot
organically in the Spring ecosystem, using its built-in DI.
- [GatekeeperBot](https://github.com/ktgram/gatekeeper) - Gatekeeper bot.
- [Native example](https://github.com/ktgram/native-example) - An example of using a bot with Kotlin Native target.
- [Web app](https://github.com/ktgram/webapp) - Example of a bot using Telegram Webapps.
# Usage
```kotlin
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](https://github.com/vendelieu/telegram-bot/wiki/Handlers) article.*
It is also possible to process updates functionally:
```kotlin
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](https://github.com/vendelieu/telegram-bot/wiki/Bot-configuration) article.
### Processing responses
To process over response or/and have more control over request flow
use [
`sendReturning()`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.interfaces.action/-action/send-returning.html)
instead
of [
`send()`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.interfaces.action/-action/send.html)
method,
which
returns [
`Response`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.types.internal/-response/index.html):
```kotlin
message { "test" }.sendReturning(user, bot).onFailure {
println("code: ${it.errorCode} description: ${it.description}")
}
```
All `sendReturning` methods returns
a [
`Response`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.types.internal/-response/index.html)
on which you can also use
methods [
`getOrNull()`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.types.internal/get-or-null.html)
, [
`isSuccess()`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.types.internal/is-success.html)
, [
`onFailure()`](https://vendelieu.github.io/telegram-bot/telegram-bot/eu.vendeli.tgbot.types.internal/on-failure.html)
### Additional resources
* There is a [wiki](https://github.com/vendelieu/telegram-bot/wiki) section that has helpful information.
* [API reference](https://vendelieu.github.io/telegram-bot/)
### Questions
You're always welcome in our [chat](https://t.me/venny_tgbot), 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.