ferobot 0.2.2

Install · Quick Start · How It Works · docs.rs

What is ferobot?

ferobot is a Telegram Bot API library for Rust. It covers all methods and types from the official API out of the box, and keeps them in sync automatically.

When Telegram ships a new Bot API version, CI picks up the spec change, regenerates the types and methods, and opens a PR. You get the update without touching anything.

The library is built around Tokio. Every bot method is async, every update runs in its own task, and the dispatcher handles routing, concurrency, and panic recovery out of the box.

Installation

Add this to your Cargo.toml:

[dependencies]
ferobot = "0.2"
tokio   = { version = "1", features = ["full"] }

Optional features you can enable:

Quick Start

Get your token from @BotFather, then:

use ferobot::{Bot, CommandHandler, Dispatcher, DispatcherOpts, HandlerResult, Updater};
use ferobot::framework::Context;

async fn start(bot: Bot, ctx: Context) -> HandlerResult {
    if let Some(msg) = ctx.effective_message() {
        msg.reply(&bot, "hello!", None).await?;
    }
    Ok(())
}

#[tokio::main]
async fn main() {
    let bot = Bot::new(std::env::var("BOT_TOKEN").unwrap()).await.unwrap();

    let mut dp = Dispatcher::new(DispatcherOpts::default());
    dp.add_handler(CommandHandler::new("start", start));

    Updater::new(bot, dp).start_polling().await.unwrap();
}

How It Works

Calling methods

Every bot method takes required arguments directly. Optional parameters are passed through a params struct, or you can skip them entirely with None:

// send a plain message
bot.send_message(chat_id, "hello").await?;

// with optional params chained via builder
bot.send_message(chat_id, "<b>hello</b>")
    .html()
    .silent()
    .reply_to(msg.message_id)
    .await?;

Shortcuts like .html(), .markdown(), .silent(), and .reply_to(id) cover the most common options. For anything else, use the params struct directly:

use ferobot::gen_methods::SendMessageParams;

let params = SendMessageParams::new()
    .parse_mode("HTML")
    .disable_notification(true);

bot.send_message(chat_id, "<b>hello</b>", Some(params)).await?;

Dispatcher and handlers

The dispatcher routes incoming updates to the first matching handler. Handlers are plain async functions:

dp.add_handler(CommandHandler::new("start", start));
dp.add_handler(MessageHandler::new("echo", mf::text(), echo));
dp.add_handler(CallbackQueryHandler::new("btn", |_| true, on_button));

Filters compose with .and(), .or(), .not():

// text that is not a command
MessageHandler::new("msg", mf::text().and(mf::command().not()), handler)

Conversations

For multi-step flows (registration, forms, wizards), use ConversationHandler. It manages state per user and routes each message to the right step:

let conv = ConversationHandler::new(
    ConversationOpts::default(),
    vec![CommandHandler::new("start", ask_name)],     // entry points
    vec![("waiting_name", vec![...])],                 // states
    vec![],                                            // fallbacks
);

State is stored in memory by default. Add the redis-storage feature for persistence across restarts.

ChatId and InputFile

ChatId accepts integers, negative group IDs, and @username strings interchangeably:

bot.send_message(123456789_i64, "hi").await?;
bot.send_message(-100123456789_i64, "hi group").await?;
bot.send_message("@username", "hi").await?;

InputFile accepts a file ID, a URL, or raw bytes at the same call site:

bot.send_photo(chat_id, "AgACAgIAAxkBAAI...").await?;                          // file_id
bot.send_photo(chat_id, "https://example.com/img.jpg").await?;                  // URL
bot.send_photo(chat_id, InputFile::memory("photo.jpg", bytes)).await?;          // bytes

Raw API

If Telegram ships a new method and you can't wait for the next ferobot release, bot.raw() lets you call any method by name with arbitrary params and get back a JSON value.

// call any method by name
let result: serde_json::Value = bot
    .raw("sendGift")
    .param("chat_id", 123456789_i64)
    .param("gift_id", "gift_abc123")
    .call()
    .await?;

File uploads work too:

bot.raw("sendPhoto")
    .param("chat_id", chat_id)
    .file("photo", InputFile::memory("photo.jpg", bytes))
    .call::<serde_json::Value>()
    .await?;

For fire-and-forget calls where you don't care about the response:

bot.raw("deleteMessage")
    .param("chat_id", chat_id)
    .param("message_id", msg_id)
    .send()
    .await?;

You can also deserialize into your own struct instead of serde_json::Value:

#[derive(serde::Deserialize)]
struct MyUser { id: i64, username: Option<String> }

let user: MyUser = bot.raw("getMe").call().await?;

In practice you rarely need this since CI keeps ferobot in sync within hours of a Telegram release. But it's a useful escape hatch when you're in a hurry or testing something new.

Always Up to Date

ferobot's types and methods are generated from tgapis/x, a machine-readable mirror of the official Telegram Bot API spec. A GitHub Actions workflow watches the spec repo and triggers regeneration whenever the API changes. The generated files (gen_types.rs, gen_methods.rs, fluent.rs) are never edited by hand.

Contributing

cargo build --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings
cargo fmt --all

One concern per PR. For bugs and features, open a GitHub issue. For security issues, email ankitchaubey.dev@gmail.com.

License

MIT - Copyright (c) 2026 Ankit Chaubey

Built by Ankit Chaubey · Telegram · docs.rs · crates.io

If ferobot saved you time, a star on GitHub means a lot.