Skip to content

A Kotlin multiplatform Telegram bot SDK, A Simple Robot Component library πŸ”₯πŸ”₯❀️‍πŸ”₯

License

LGPL-3.0, GPL-3.0 licenses found

Licenses found

LGPL-3.0
COPYING.LESSER
GPL-3.0
COPYING
Notifications You must be signed in to change notification settings

simple-robot/simbot-component-telegram

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

simbot logo

~ Simple Robot ~
Telegram Component

release release
stars forks watchers repo size issues last commit copying

δΈ­ζ–‡ | English

Caution

WIP.

Some thoughts? Feel free to share or join the communities.

Warning

This content is machine-translated.

This is a Telegram Bot API/SDK Kotlin multi-platform library based on Kotlin coroutines, efficient and asynchronous, Java-friendly.

It is also a component library of Simple Robot v4 (simbot), which is a subproject of simbot. With the capabilities provided by the simbot core library, it can support more advanced encapsulation, as well as component collaboration, Spring support, and more.

Serialization and network requests are based on Kotlin serialization and Ktor.

Documentation

Setup

To use the simbot component library, you first need to add the core implementation of simbot (such as the core library (simbot-core) or Spring Boot starter (simbot-core-spring-boot-starter)), and then add the component library dependencies of the Telegram (simbot-component-telegram-core).

Note

The version of the simbot core implementation library (SIMBOT_VERSION below) goes here for reference;

Telegram Component library versions (VERSION below) go to the release reference.

With simbot core

Gradle

build.gradle.kts

plugins {
    kotlin("...") version "..."
}

dependencies {
    implementation("love.forte.simbot:simbot-core:${SIMBOT_VERSION}")
    implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
}

Maven

pom.xml

<dependencies>
    <dependency>
        <groupId>love.forte.simbot</groupId>
        <artifactId>simbot-core-jvm</artifactId>
        <version>${SIMBOT_VERSION}</version>
    </dependency>
    <dependency>
        <groupId>love.forte.simbot.component</groupId>
        <artifactId>simbot-component-telegram-core-jvm</artifactId>
        <version>${VERSION}</version>
    </dependency>
</dependencies>

With simbot spring boot starter

Gradle

build.gradle.kts

plugins {
    kotlin("jvm") version "..."
}

dependencies {
    implementation("love.forte.simbot:simbot-core-spring-boot-starter:${SIMBOT_VERSION}")
    implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
}

Maven

pom.xml

<dependencies>
    <dependency>
        <groupId>love.forte.simbot</groupId>
        <artifactId>simbot-core-spring-boot-starter</artifactId>
        <version>${SIMBOT_VERSION}</version>
    </dependency>
    <dependency>
        <groupId>love.forte.simbot.component</groupId>
        <artifactId>simbot-component-telegram-core-jvm</artifactId>
        <version>${VERSION}</version>
    </dependency>
</dependencies>

Ktor client engine

The Telegram component uses Ktor as the HTTP client implementation, but does not rely on any specific engine by default.

Therefore, you need to choose and use a Ktor Client engine implementation.

You can go to the Ktor documentation to select a suitable Client Engine for your platform.

Take the JVM platform as an example:

Gradle
runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
Maven
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-java-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>

Examples

simbot core

suspend fun main() {
    val app = launchSimpleApplication { 
        useTelegram() // install Telegram Component
    }

    // subscribe to events
    app.listeners {
        // subscribe to ChatGroupMessageEvent 
        listen<ChatGroupMessageEvent> { event ->
            // process event...
            event.reply("Hello!")
            event.reply(At(event.authorId) + "Where are you?".toText())

            // Required an result
            EventResult.empty()
        }

        // subscribe to ChatGroupMessageEvent
        process<TelegramPrivateMessageEvent> { event ->
            // process event...
            event.content().send("Welcome, " + At(event.member().id))

            // Without result in `process<T>` 
        }
    }
    
    // register bots
    app.telegramBots {
        // register a bot via token
        val bot = register(token = "botaaabbb.123123444") {
            // Config...
            // The source stdlib bot config 
            botConfiguration {
                apiClientConfigurer {
                    engine {
                        // A proxy?
                        proxy = ProxyBuilder.http("http://127.0.0.1:7790")
                    }
                }

                // Enable longPolling?
                longPolling = LongPolling(
                    limit = 100,
                    timeout = 10.minutes.inWholeSeconds.toInt(),
                    allowedUpdates = setOf(UpdateValues.MESSAGE_NAME),
                    // Enable retry?
                    retry = LongPolling.Retry()
                )
            }
        }

        // start the bot
        bot.start()
    }

    
    app.join()   
}

simbot Spring Boot starter

@SpringBootApplication
@EnableSimbot // enable
class App

fun main(args: Array<String>) {
    runApplication<App>(*args)
}

@Component
class MyHandles {

    @Listener // subscribe to ChatGroupMemberIncreaseEvent
    suspend fun handleMemberIncrease(event: ChatGroupMemberIncreaseEvent) {
        // ...
    }
    
    @Filter("Hello.*")
    @Listener // subscribe to ChatGroupMessageEvent
    suspend fun handleGroupMessage(event: ChatGroupMessageEvent) {
        event.reply("Hello!")
    }
}

The configuration file *.bot.json

Comments are not supported. Remember to clean them up when you use them.

{
    "component": "simbot.telegram",
    "ticket": {
        "token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
    },
    // config and its properties are optional and default to `null`.
    "config": {
        "server": null,
        "proxy": null,
        "longPolling": null
    }
}
{
    "component": "simbot.telegram",
    "ticket": {
        "token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
    },
    // config and its properties are optional and default to `null`.
    "config": {
        "server": null,
        "proxy": null,
        // config the `longPolling` to subscribe evnets
        "longPolling": {
            "limit": 100
        }
    }
}

CONTRIBUTING

See CONTRIBUTING.md for more information!

We welcome you and look forward to it feedback or pull request, Thank you for your contribution and support!

License

simbot-component-telegram is open source under the LGPLv3 licence。

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General 
Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) 
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied 
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more 
details.

You should have received a copy of the GNU Lesser General Public License along with this program. 
If not, see <https://www.gnu.org/licenses/>.