ZethRise/Ronami: manages the full lifecycle of Telegram bot applications

Full-featured, elegant Telegram Bot framework in Rust with Bot API 10.2+ coverage.

v1.1.0 — Ronami is a modern Telegram Bot framework in Rust, evolved from teloxide to deliver up-to-date Telegram Bot API 10.2+ coverage, refreshed crate naming, and active maintenance. this Project is Vibe Coded with Ai so expect bugs and errors

What Ronami does

Ronami manages the full lifecycle of Telegram bot applications. It combines strongly-typed request and response structures with a declarative dependency-injection dispatcher (dptree), stateful conversational dialogues, resilient network adaptors, and macro-driven command routing.

Telegram Bot API Server (:8081 / cloud)
                 │
                 ▼
       Ronami Core (HTTP / Multipart)
                 │
                 ▼
    Adaptors (Throttle / Trace / ParseMode / Erased)
                 │
                 ▼
         Dispatcher (dptree DI)
                 │
                 ▼
       Your Bot Handlers & Dialogues

Highlights

• Telegram Bot API 10.2: Full coverage including Ephemeral Messages (editEphemeralMessageText, editEphemeralMessageMedia, editEphemeralMessageCaption, editEphemeralMessageReplyMarkup, deleteEphemeralMessage, is_ephemeral, receiver_user, ephemeral_message_id), Communities (Community, CommunityChatAdded, CommunityChatJoined, CommunityChatRemoved), Rich Messages (InputRichBlock, InputRichMessageMedia, InputMediaVoiceNote, InputRichMessage), join request queries, guest mode, and user payment subscriptions (BotSubscriptionUpdated).
• Declarative Dispatching: Functional chain-of-responsibility routing powered by dptree. Inject dependencies, compose pipelines, and cleanly isolate event handlers.
• Stateful Dialogues: Built-in finite-state-machine (FSM) conversations with interchangeable storage backends: In-Memory, Redis, SQLite, and PostgreSQL.
• Pluggable Adaptor Stack: Layer decorators for automatic request throttling, default parse modes (HTML / MarkdownV2), structured trace logging, and cache tiers.
• Macro-Driven Commands: Parse and dispatch bot command menus declaratively with #[derive(BotCommands)].
• Local & Cloud Bot API: Seamlessly configure official cloud endpoints or self-hosted Bot API servers (e.g. http://127.0.0.1:8081).

Quick start

Requirements

• Rust 1.85+ (stable or nightly)
• A Telegram bot token from @BotFather (Note: BotFather enables Privacy Mode by default in groups; disable via /setprivacy if your bot needs to process non-command group messages)

Add dependency

Add Ronami to your Cargo.toml:

[dependencies]
ronami = { version = "1.0.0", features = ["macros"] }
tokio = { version = "1.47", features = ["rt-multi-thread", "macros"] }
log = "0.4"
pretty_env_logger = "0.5"

Write your bot

Set your token:

export RONAMI_TOKEN="123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ"

Create src/main.rs:

use ronami::prelude::*;

#[tokio::main]
async fn main() {
    pretty_env_logger::init();
    log::info!("Starting dice bot...");

    let bot = Bot::from_env();

    ronami::repl(bot, |bot: Bot, msg: Message| async move {
        bot.send_dice(msg.chat.id).await?;
        Ok(())
    })
    .await;
}

Run with cargo run.

Command routing

Define typed command enums with doc comments automatically converted into Telegram help descriptions:

use ronami::{prelude::*, utils::command::BotCommands};

#[derive(BotCommands, Clone)]
#[command(rename_rule = "lowercase", description = "These commands are supported:")]
enum Command {
    #[command(description = "Display this help text.")]
    Help,
    #[command(description = "Handle a username.")]
    Username(String),
    #[command(description = "Handle a username and age.", parse_with = "split")]
    UsernameAndAge { username: String, age: u8 },
}

async fn answer(bot: Bot, msg: Message, cmd: Command) -> ResponseResult<()> {
    match cmd {
        Command::Help => {
            bot.send_message(msg.chat.id, Command::descriptions().to_string()).await?;
        }
        Command::Username(username) => {
            bot.send_message(msg.chat.id, format!("Username: @{username}")).await?;
        }
        Command::UsernameAndAge { username, age } => {
            bot.send_message(msg.chat.id, format!("User @{username}, Age: {age}")).await?;
        }
    }
    Ok(())
}

#[tokio::main]
async fn main() {
    pretty_env_logger::init();
    let bot = Bot::from_env();
    Command::repl(bot, answer).await;
}

Migration from teloxide

Ronami is an API-compatible drop-in successor to teloxide. Rename dependencies and environment variables:

Project layout

crates/ronami/          High-level framework: dispatching, repls, dialogues
crates/ronami-core/     Core Bot API client, types, payloads, and adaptors
crates/ronami-macros/   Procedural macros for derive(BotCommands)
examples/               Production-ready bot examples and patterns
media/                  Brand assets and diagrams

Security

Do not report security-sensitive issues or vulnerabilities in public issues. Send private reports to ZethRise@proton.me.