`telers`

An asynchronous framework for Telegram Bot API written in Rust

Telers make it easy to create Telegram bots in Rust.

Before you start, make sure that you have a basic understanding of the Telegram Bot API, because types and methods in the library have the same fields and types as in the documentation.

More information about this crate can be found in the crate documentation.

Highlights

Asynchronous. Built on top of Tokio, a powerful asynchronous runtime.
Easy to use. Provides a simple and intuitive API for creating bots.
Based on aiogram. Inspired by the framework written in Python and tries to provide a similar functionality.
Routers, Middlewares, Filters and Handlers. Provides a powerful system of routers, middlewares, filters and handlers to make your code more readable and maintainable, and simplify the creation of bots.
Extractors. Have similar system of extractors as in axum and actix.
Smart filters. Analog of "magic" filters in aiogram.

Getting started

Add telers to your Cargo.toml:

[dependencies]
telers = "1.0"
tokio = { version = "1", features = ["macros", "rt"] }

To enable logging, you may also want to add tracing and tracing-subscriber.

Create a bot with @BotFather to get a token, then put it in the BOT_TOKEN environment variable and run the following echo bot:

use telers::{
    enums::UpdateType,
    event::telegram::{Handler, HandlerResult},
    types::{Message, MessageShortcuts as _},
    Bot, Dispatcher, Router,
};

async fn echo_handler(bot: Bot, message: Message) -> HandlerResult<()> {
    bot.send(message.copy_to(message.chat().id()))
        .await?;
    Ok(())
}

#[tokio::main(flavor = "current_thread")]
async fn main() {
    tracing_subscriber::fmt().init();

    let bot = Bot::from_env();

    let router =
        Router::new("main").on_message(|observer| observer.register(Handler::new(echo_handler)));

    let dispatcher = Dispatcher::builder()
        .main_router(router.configure_default())
        .bot(bot)
        .allowed_update(UpdateType::Message)
        .build();

    match dispatcher.run_polling().await {
        Ok(()) => tracing::info!("Bot stopped"),
        Err(err) => tracing::error!(error = %err, "Bot stopped"),
    }
}

For more, check out the crate documentation and the examples below.

Examples

Echo bot. This example shows how to create an echo bot.
Context. This example shows how to use context to save data.
Extensions. This example shows how to use extensions to save data.
Extractor. This example shows how to use extractor to extract data.
Text formatting. This example shows how to format text.
Text rendering. This example shows how to render a message's text and entities back to HTML or MarkdownV2.
Smart filter. This example show how to use smart filter.
Text case filters. This example shows how to create text case filters.
Stats updates middleware. This example shows how to create a middleware that count incoming updates.
Input file. This example shows how to send files by the bot.
Download file. This example shows how to download files sent to the bot.
Callback data. This example shows how to pack structured data into inline keyboard buttons and unpack it in handlers.
Finite state machine. This example shows how to use a finite state machine (conversation).
Error handling. This example shows how to handle errors of handlers, filters and middlewares in one place.
Router tree. This example shows how to create a router tree.
Bot http client. This example shows how to set a custom bot HTTP client.
Axum and echo bot. This example shows how to create an echo bot and run it concurrently with polling axum server.
Axum webhook. This example shows how to setup webhooks for a bot using axum server.
Managed bot. This example shows how to create a managed bot that echoes messages and handles managed bot creation events by spawning separate dispatchers with a shared shutdown signal.

You may consider checking out this directory for more examples.

Community

🇺🇸 @telers_en
🇷🇺 @telers_ru

License

This project is licensed under either of the following licenses, at your option:

telers 1.0.0-beta.9

telers