Crate telers 

An asynchronous framework for the Telegram Bot API written in Rust.

telers makes it easy to create Telegram bots: it provides a system of routers, middlewares, filters and handlers (inspired by aiogram), and an extractor system for handler arguments similar to the ones in axum and actix. Types and methods mirror the Telegram Bot API documentation: the same objects with the same fields, plus generated helper methods and builders.

Quick start

An echo bot (reads the token from the BOT_TOKEN environment variable):

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

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

#[tokio::main(flavor = "current_thread")]
async fn main() {
    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();

    dispatcher.run_polling().await.expect("Polling failed");
}

Where to go next

• router — how events are routed to observers and handlers, controlled by EventReturn
• dispatcher — polling, allowed updates, startup/shutdown events
• middlewares — outer and inner middlewares
• filters — ready-made and custom filters, including the SmartFilter
• extractor — extracting handler arguments from events and the Context
• fsm — finite state machine (conversations) with pluggable storage
• types and methods — generated Telegram Bot API objects and requests
• utils — text formatting and rendering helpers, and more

More examples can be found in the examples directory.

Re-exports

pub use client::Bot;

pub use context::Context;

pub use dispatcher::Builder as DispatcherBuilder;

pub use dispatcher::Dispatcher;

pub use either::Either;

pub use extensions::Extension;

pub use extensions::Extensions;

pub use extractor::Extractor;

pub use filters::Filter;

pub use filters::FilterResult;

pub use fsm::Context as FSMContext;

pub use request::Request;

pub use router::Configured as RouterConfigured;

pub use router::Router;

Modules

client

This module contains submodules with components for sending requests to the Telegram Bot API, its conguration and the main entry point for the library - the Bot struct.

context

Context is a type that is used to transmit data between processing-units when propagating an event. The context is created at the start of the event propagation by the Dispatcher and passed to every processing-unit. Processing-units can add their own data to context and use data from context that was added by others.

dispatcher

Dispatcher is the main part of the library, which contains functionality for handling updates and dispatching them to the router. You can create Dispatcher using Builder.

either

enums

Enum helpers and discriminator types for Telegram objects.

errors

Errors that can be returned by the library.

event

Event observers, handlers and propagation control.

extensions

Extension is a type that is used to transmit data between processing-units when propagating an event. Extensions are created at the start of the event propagation by the Dispatcher and passed to every processing-unit. Processing-units can add their own data to extensions and use data that was added by others.

extractor

This module contains functionality for extracting data to the handler arguments.

filters

Filters are the main part of the library used to filter incoming updates and allow calling handlers by their data (text, chat, user, command, state, db, etc.) and other conditions.

fsm

This module contains the implementations of the finite state machine.

methods

Telegram Bot API methods and their request builders.

middlewares

This module contains inner and outer middlewares.

request

router

Router combines all event observers.

types

Telegram Bot API data types and helper models.

utils

Helper utilities around the core routing flow.

webhooks

Receiving updates via webhooks instead of long polling (feature webhooks).

Derive Macros

FromContext

Derive an implementation of Extractor for the given type.

FromEvent

Derive an implementation of Extractor for the given type.