rustigram

A comprehensive, async-first Rust framework for the Telegram Bot API.

[dependencies]
rustigram = "0.9.7"
tokio     = { version = "1", features = ["full"] }

Overview

rustigram is a typed, ergonomic Rust library for building Telegram bots. Every Bot API method is exposed as an awaitable builder — set only the parameters you need, then .await. Incoming updates are routed through a composable filter-handler pipeline running concurrently on tokio.

The framework is split into focused crates so you can depend on only what you need:

Crate	Purpose
`rustigram-types`	All Bot API types, fully serde-serialisable
`rustigram-api`	HTTP client and typed method builders
`rustigram-bot`	Dispatcher, filters, handlers, FSM, update listeners
`rustigram-macros`	Procedural macros (`#[handler]`, `#[derive(DialogueState)]`)
`rustigram`	Public facade re-exporting all sub-crates

Supported Bot API version: 9.7 (May 2026) Minimum Rust version: 1.75

Quick start

use rustigram::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();

    let bot = Bot::new(std::env::var("BOT_TOKEN")?)?;

    bot.dispatcher()
        .on(filters::command("start"), handler_fn(start))
        .on(filters::command("help"),  handler_fn(help))
        .on(filters::message(),        handler_fn(echo))
        .build()
        .polling()
        .await?;

    Ok(())
}

async fn start(ctx: Context) -> BotResult<()> {
    if let Some(r) = ctx.reply("Hello! Send me any message.") {
        r.await?;
    }
    Ok(())
}

async fn help(ctx: Context) -> BotResult<()> {
    if let Some(r) = ctx.reply("/start — greeting\n/help — this message") {
        r.await?;
    }
    Ok(())
}

async fn echo(ctx: Context) -> BotResult<()> {
    if let (Some(text), Some(chat_id)) = (ctx.text(), ctx.chat_id()) {
        ctx.bot.send_message(chat_id, text).await?;
    }
    Ok(())
}

Get your bot token from @BotFather, then:

BOT_TOKEN=your_token cargo run

Architecture

Telegram
   │  getUpdates (long poll) or POST (webhook)
   ▼
Dispatcher
   ├── Route 1: filter::command("start")  ──► handler A  ─┐
   ├── Route 2: filter::callback_query()  ──► handler B    │  tokio::spawn
   ├── Route 3: filter::message()         ──► handler C    │  (concurrent)
   └── Fallback                           ──► handler D  ──┘
                                                │
                                           Context { update, bot }
                                                │
                                     ctx.bot.send_message(...).await

Each incoming update is dispatched in its own tokio::spawn task. Handlers run concurrently — a slow handler does not block others. The dispatcher evaluates routes in registration order and stops at the first match.

Receiving updates

Long polling

Long polling is the simplest mode and requires no public server.

bot.dispatcher()
    .on(filters::message(), handler_fn(my_handler))
    .build()
    .polling()
    .await?;

The poller automatically advances the offset after each batch, so updates are never processed twice. Transient network errors (timeout, connection reset) are retried automatically. Rate-limit responses (HTTP 429) honour the retry_after value from Telegram.

Webhook

// Register the webhook URL with Telegram once
bot.client
    .set_webhook("https://example.com/")
    .secret_token("change_me")
    .await?;

// Start the axum-based server
bot.dispatcher()
    .on(filters::message(), handler_fn(my_handler))
    .build()
    .webhook("0.0.0.0:8443".parse()?)
    .await?;

Supported Telegram webhook ports: 443, 80, 88, 8443.

The secret token is validated on every incoming request. Requests with a missing or incorrect X-Telegram-Bot-Api-Secret-Token header are rejected with HTTP 401.

Sending messages

Every API method returns a builder. Call only the setters you need, then .await.

// Plain text
ctx.bot.send_message(chat_id, "Hello!").await?;

// With formatting and a reply
ctx.bot
    .send_message(chat_id, "<b>Bold</b> and <i>italic</i>")
    .parse_mode(ParseMode::HTML)
    .reply_to(message_id)
    .await?;

// Disable notification
ctx.bot
    .send_message(chat_id, "Silent message")
    .disable_notification(true)
    .await?;

// Photo from URL
ctx.bot
    .send_photo(chat_id, InputFile::Url("https://example.com/photo.jpg".into()))
    .caption("A photo")
    .await?;

// Forward a message
ctx.bot.forward_message(to_chat_id, from_chat_id, message_id).await?;

// Delete a message
ctx.bot.delete_message(chat_id, message_id).await?;

// Edit an existing message
ctx.bot
    .edit_message_text(chat_id, message_id, "Updated text")
    .parse_mode(ParseMode::HTML)
    .await?;

Available send methods

Method	Description
`send_message`	Text (up to 4096 characters)
`send_photo`	Photo (.jpg, .png, etc.)
`send_audio`	Audio file treated as music
`send_document`	General file
`send_video`	Video (MPEG4)
`send_animation`	GIF or silent H.264 video
`send_voice`	Voice note (OGG/OPUS)
`send_video_note`	Rounded-square video
`send_sticker`	.WEBP / .TGS / .WEBM sticker
`send_location`	Map point, optionally live
`send_contact`	Phone contact
`send_poll`	Native poll or quiz
`send_dice`	Animated dice/emoji
`send_invoice`	Payment invoice
`send_media_group`	Album of 2–10 media items
`send_chat_action`	Typing indicator etc.
`forward_message`	Forward from another chat
`copy_message`	Copy without forward header

Filters

Filters are composable predicates evaluated against an incoming Context. The dispatcher calls the first handler whose filter returns true.

Built-in filters

use rustigram::prelude::filters;

filters::message()                    // Any Message update
filters::edited_message()             // Any EditedMessage update
filters::callback_query()             // Any CallbackQuery update
filters::inline_query()               // Any InlineQuery update
filters::command("start")             // /start (case-insensitive, strips @BotName)
filters::text("exact string")         // Exact text match
filters::text_contains("substring")   // Substring match
filters::callback_data("btn_ok")      // Exact callback data
filters::callback_data_prefix("nav:") // Callback data prefix
filters::private()                    // Private chats only
filters::group()                      // Groups and supergroups
filters::any()                        // Always passes

Combinators

use rustigram::prelude::filters;
use rustigram_bot::filter::FilterExt;

// Both must match
filters::message().and(filters::private())

// Either can match
filters::private().or(filters::group())

// Invert
filters::private().not()

// Chain freely
filters::command("ban")
    .and(filters::group())
    .and(filter_fn(|ctx| is_admin(ctx)))

Custom filters

use rustigram_bot::filter::{filter_fn, Filter};

let has_photo = filter_fn(|ctx| {
    ctx.message().and_then(|m| m.photo.as_ref()).is_some()
});

bot.dispatcher()
    .on(has_photo, handler_fn(photo_handler))
    .build()
    .polling()
    .await?;

Handlers

A handler is any async function with the signature async fn(Context) -> BotResult<()>.

use rustigram::prelude::*;

async fn my_handler(ctx: Context) -> BotResult<()> {
    // ctx.bot       — the API client, call any method
    // ctx.update    — the raw Update
    // ctx.text()    — message text or caption
    // ctx.command() — command name without / and @BotName
    // ctx.chat_id() — chat ID from message or callback query
    // ctx.from_id() — sender user ID
    // ctx.reply(t)  — send a reply to the current message

    if let Some(r) = ctx.reply("Got it!") {
        r.await?;
    }
    Ok(())
}

Handlers can also be closures:

bot.dispatcher()
    .on(filters::command("ping"), handler_fn(|ctx: Context| async move {
        if let Some(r) = ctx.reply("pong") { r.await?; }
        Ok(())
    }))
    .build()
    .polling()
    .await?;

Callback queries and inline keyboards

use rustigram::prelude::*;
use rustigram_types::keyboard::{InlineKeyboardMarkup, InlineKeyboardButton};

async fn menu(ctx: Context) -> BotResult<()> {
    let markup = InlineKeyboardMarkup::new()
        .row(vec![
            InlineKeyboardButton::callback("Yes", "answer:yes"),
            InlineKeyboardButton::callback("No",  "answer:no"),
        ])
        .row(vec![
            InlineKeyboardButton::url("Documentation", "https://core.telegram.org/bots/api"),
        ]);

    if let Some(chat_id) = ctx.chat_id() {
        ctx.bot
            .send_message(chat_id, "Make a choice:")
            .reply_markup(ReplyMarkup::InlineKeyboard(markup))
            .await?;
    }
    Ok(())
}

async fn handle_answer(ctx: Context) -> BotResult<()> {
    if let Some(q) = ctx.callback_query() {
        let answer = q.data.as_deref().unwrap_or("").trim_start_matches("answer:");
        ctx.bot
            .answer_callback_query(&q.id)
            .text(format!("You chose: {answer}"))
            .await?;
    }
    Ok(())
}

// Registration
bot.dispatcher()
    .on(filters::command("menu"),               handler_fn(menu))
    .on(filters::callback_data_prefix("answer:"), handler_fn(handle_answer))
    .build()
    .polling()
    .await?;

Conversation state (FSM)

DialogueStorage tracks per-user state keyed by (chat_id, user_id). State values are type-erased with Any so any type works without a shared trait.

use rustigram::prelude::*;
use rustigram_bot::state::DialogueStorage;
use std::sync::Arc;

#[derive(Clone)]
enum RegistrationState {
    AwaitingName,
    AwaitingEmail { name: String },
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let bot = Bot::new(std::env::var("BOT_TOKEN")?)?;
    let storage = Arc::new(DialogueStorage::new());

    bot.dispatcher()
        .on(filters::command("register"), {
            let s = storage.clone();
            handler_fn(move |ctx| { let s = s.clone(); async move { start(ctx, s).await } })
        })
        .on(filters::message(), {
            let s = storage.clone();
            handler_fn(move |ctx| { let s = s.clone(); async move { step(ctx, s).await } })
        })
        .build()
        .polling()
        .await?;

    Ok(())
}

async fn start(ctx: Context, storage: Arc<DialogueStorage>) -> BotResult<()> {
    let (chat_id, user_id) = match (ctx.chat_id(), ctx.from_id()) {
        (Some(ChatId::Id(c)), Some(u)) => (c, u),
        _ => return Ok(()),
    };
    storage.set(chat_id, user_id, RegistrationState::AwaitingName);
    if let Some(r) = ctx.reply("What is your name?") { r.await?; }
    Ok(())
}

async fn step(ctx: Context, storage: Arc<DialogueStorage>) -> BotResult<()> {
    let (chat_id, user_id) = match (ctx.chat_id(), ctx.from_id()) {
        (Some(ChatId::Id(c)), Some(u)) => (c, u),
        _ => return Ok(()),
    };
    let text = match ctx.text() { Some(t) => t.to_owned(), None => return Ok(()) };

    match storage.get::<RegistrationState>(chat_id, user_id) {
        Some(RegistrationState::AwaitingName) => {
            storage.set(chat_id, user_id, RegistrationState::AwaitingEmail { name: text.clone() });
            if let Some(r) = ctx.reply(format!("Nice to meet you, {text}! What is your email?")) { r.await?; }
        }
        Some(RegistrationState::AwaitingEmail { name }) => {
            storage.remove(chat_id, user_id);
            if let Some(r) = ctx.reply(format!("Registered: {name} <{text}>")) { r.await?; }
        }
        None => {}
    }
    Ok(())
}

Shared state

StateStorage is a thread-safe, type-keyed store for data shared across all handlers — database connection pools, configuration, counters, etc.

use rustigram_bot::state::StateStorage;
use std::sync::Arc;

#[derive(Clone)]
struct AppConfig {
    admin_id: i64,
    prefix: String,
}

let store = StateStorage::new();
store.insert(AppConfig { admin_id: 123456, prefix: "!".into() });
store.insert(my_db_pool);

// Inside a handler (store captured via Arc):
let config = store.get::<AppConfig>().unwrap();

File uploads

InputFile accepts three variants:

use rustigram_api::BotClient;
use rustigram_types::file::InputFile;

// Re-send an existing Telegram file by file_id (most efficient)
InputFile::FileId("AgACAgIAAxkBAAI...".into())

// Download from a URL (Telegram fetches it; max 20 MB for most types)
InputFile::Url("https://example.com/document.pdf".into())

// Upload raw bytes
InputFile::Bytes {
    filename: "report.pdf".into(),
    data: std::fs::read("report.pdf")?,
    mime_type: "application/pdf".into(),
}

All three variants share the same API:

ctx.bot
    .send_document(chat_id, InputFile::Bytes {
        filename: "data.csv".into(),
        data: csv_bytes,
        mime_type: "text/csv".into(),
    })
    .caption("Your export")
    .await?;

Downloading a file sent to your bot:

let file = ctx.bot.get_file(&document.file_id).await?;
let bytes = ctx.bot.download_file(&file.file_path.unwrap()).await?;

Payments and Stars

Telegram Stars (XTR)

use rustigram_types::payments::LabeledPrice;

ctx.bot
    .send_invoice(
        chat_id,
        "Premium Access",
        "30 days of premium features",
        "payload_premium_30d",
        "XTR",
        vec![LabeledPrice { label: "30-day plan".into(), amount: 100 }],
    )
    .await?;

No provider_token is needed for Stars. The amount is in whole Stars.

Handling purchases

async fn handle_pre_checkout(ctx: Context) -> BotResult<()> {
    if let Some(q) = ctx.update.kind.as_pre_checkout_query() {
        ctx.bot
            .answer_pre_checkout_query(&q.id, true)
            .await?;
    }
    Ok(())
}

Star balance

let balance = ctx.bot.get_my_star_balance().await?;
println!("Balance: {} Stars", balance.amount);

Webhook setup

A complete production webhook setup:

use rustigram::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let token = std::env::var("BOT_TOKEN")?;
    let webhook_url = std::env::var("WEBHOOK_URL")?;   // e.g. https://bot.example.com
    let secret = std::env::var("WEBHOOK_SECRET")?;
    let bind_addr = std::env::var("BIND_ADDR").unwrap_or("0.0.0.0:8443".into());

    let bot = Bot::new(&token)?;

    // Register with Telegram
    bot.client
        .set_webhook(&webhook_url)
        .secret_token(&secret)
        .max_connections(40)
        .drop_pending_updates(true)
        .await?;

    tracing::info!("Webhook registered at {}", webhook_url);

    bot.dispatcher()
        .on(filters::command("start"), handler_fn(start_handler))
        .on(filters::message(),        handler_fn(echo_handler))
        .build()
        .webhook(bind_addr.parse()?)
        .await?;

    Ok(())
}

To remove the webhook and switch back to polling:

bot.client.delete_webhook().drop_pending_updates(true).await?;

Local Bot API server

Run a local Bot API server for higher limits:

File upload up to 2 GB (vs 50 MB)
File download up to 2 GB (vs 20 MB)
Up to 100,000 webhook connections
HTTP webhooks on any port and local IP
getFile returns absolute local path

Point rustigram at your local server:

use rustigram_api::ClientConfig;
use std::time::Duration;

let config = ClientConfig::new(token)?
    .api_base_url("http://localhost:8081")
    .timeout(Duration::from_secs(120));

let client = rustigram_api::BotClient::new(config)?;

Error handling

BotError covers all failure modes:

use rustigram_bot::error::BotError;
use rustigram_api::Error as ApiError;

match result {
    Err(BotError::Api(ApiError::Api { error_code: 403, .. })) => {
        // Bot was blocked by the user
    }
    Err(BotError::Api(ApiError::RateLimit { retry_after })) => {
        // Flood control — wait retry_after seconds
    }
    Err(BotError::Api(ApiError::Api { error_code: 400, description, .. })) => {
        // Bad request — check description
        eprintln!("Bad request: {}", description);
    }
    Err(e) => eprintln!("Unexpected error: {}", e),
    Ok(_) => {}
}

Polling and webhook modes handle RateLimit and transient network errors automatically. Only non-recoverable errors propagate to your application.

Useful error predicates

let err: rustigram_api::Error = ...;

err.is_rate_limit()     // true for HTTP 429
err.is_blocked()        // true when bot was blocked by user
err.is_chat_not_found() // true for "chat not found" 400s
err.retry_after()       // Some(secs) when rate-limited

Examples

The examples/ directory contains complete runnable bots:

Example	Description
`echo_bot`	Minimal bot — echoes any message back
`inline_keyboard`	Inline buttons and callback query routing
`webhook_bot`	Production webhook server setup
`state_machine`	Multi-step conversation with FSM

Run any example:

BOT_TOKEN=your_token cargo run --example echo_bot

Running the tests

The test suite requires no bot token — all tests use hand-crafted in-memory data.

cargo test --workspace

Suite	Count	What is tested
`client_tests`	11	Token validation, error types, client config
`types_tests`	23	Serde round-trips, helper methods, Update deserialization
`dispatcher_tests`	20	All filters, combinators, Context helpers, state storage

Contributing

Contributions are welcome. Please open an issue before submitting a pull request for non-trivial changes.

Guidelines:

Code style follows rustfmt defaults — run cargo fmt before committing
All public items must have doc comments
New features should include tests
Avoid unwrap() in library code; propagate errors with ?

Running checks locally:

cargo fmt --check
cargo clippy --workspace -- -D warnings
cargo test --workspace

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
crates		crates
docs-theme		docs-theme
site		site
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
release-plz.toml		release-plz.toml

Folders and files

Latest commit

History

Repository files navigation

rustigram

Overview

Table of Contents

Quick start

Architecture

Receiving updates

Long polling

Webhook

Sending messages

Available send methods

Filters

Built-in filters

Combinators

Custom filters

Handlers

Callback queries and inline keyboards

Conversation state (FSM)

Shared state

File uploads

Payments and Stars

Telegram Stars (XTR)

Handling purchases

Star balance

Webhook setup

Local Bot API server

Error handling

Useful error predicates

Examples

Running the tests

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Contributors

Uh oh!

Languages