ferogram
Ferogram
A native, elegant MTProto framework for building Telegram clients and bots.
Everything you need for Telegram: direct MTProto, bots, user accounts, and voice & video calls in one elegant framework.
One engine.
Two languages.
Rust and Python run on exactly the same networking, encryption, MTProto implementation, TL parser, transport, update handling, and session management. Python is not a separate reimplementation, it is powered by the same compiled Rust core.
Python calls cross an FFI boundary once, into the same Rust crates that power the native ferogram client.
Same engine, your syntax
Install, write a bot, and read the docs, all in the language you already use.
use ferogram::Client; const API_ID: i32 = 0; const API_HASH: &str = ""; #[tokio::main] async fn main() -> anyhow::Result<()> { let (client, _) = Client::quick_connect("my.session", API_ID, API_HASH).await?; client.send_message("me", "Hello from ferogram!").await?; Ok(()) }
import asyncio from ferogram import Client app = Client("myaccount", api_id=0, api_hash="", phone="+1234567890") async def main(): async with app as client: await client.send_message("me", "Hello from ferogram!") asyncio.run(main())
Built for production
Native performance, full control
An async Rust core talking directly to Telegram's wire protocol, giving you full control over every request and response.
Composable filters
Route updates by combining filters with &, |, and ! instead of nesting if-statements.
Finite-state conversations
ferogram-fsm drives multi-step bot flows with pluggable, swappable state storage.
Pluggable sessions
Binary file, SQLite, LibSQL (Turso), or a portable string backend, or bring your own.
Built-in MTProxy
Classic, DD, and FakeTLS transports, with tg://proxy links parsed and connected automatically.
Gap-safe updates
ferogram-msgbox tracks pts/qts/seq, spots gaps in the update stream, and requests a diff to fix them.
Voice & video calls
TgCalls streams into group and one-on-one calls with a few lines, using FFmpeg under the hood.
One core, two languages
Rust and Python share the exact same protocol implementation, so fixes and speedups land in both at once.
Raw API escape hatch
Reach for client.invoke() and call any TL function directly when the high-level API isn't enough.
Everything a real client needs
MTProxy, rich messaging, CDN downloads, high-speed transfers, and steady performance under load, plus a lot more that doesn't fit in a headline.
The goal is to stay out of your way: simple things should be simple, and advanced things should still be possible.
- Rich messaging: text, media, albums, polls, dice, games, reactions, scheduled messages
- HTML & Markdown: full parse and generate support for both formats
- Inline & reply keyboards: buttons, callbacks, inline mode
- Reactions & stickers: granular reaction API with paid Stars reactions, sticker sets, custom emoji
- Drafts: save, sync, and clear drafts across devices
- Proxy support: SOCKS5 with optional auth
- MTProxy: Classic, DD, and FakeTLS transports, via link or manual config
- Transport probing: races transports, connects via whichever is fastest
- Resilient connect: DNS-over-HTTPS and special-config fallback when TCP is blocked
- CDN: transparent CDN download handling, no extra calls needed
- Concurrent transfers: parallel uploads/downloads with pause, resume, cancel, and progress tracking
- Resumable transfers: checkpointed uploads/downloads that survive crashes
- Router & dispatcher: composable filters (&, |, !) for expressive handlers
- FSM: type-safe finite state machine for multi-step conversations
- Middleware: rate limiting, tracing, panic recovery
- Conversations: ask/wait sequential request-response flows outside the router
- Flexible login: phone + 2FA (SRP), bot token, or QR code, with exportable session strings
- Session backends: file, in-memory, string, SQLite, LibSQL
- Peer resolution: usernames, phone numbers, links, or raw IDs, resolved cache-first
- Gap-safe updates: pts/qts/seq tracking with automatic diff recovery on reconnect
- Full admin toolkit: ban, kick, restrict, promote, and transfer ownership
- Invite links: create, edit, revoke, track joins, approve or decline requests
- Forum topics: create, edit, and manage topics in forum supergroups
- Privacy controls: per-key rules with granular allow/disallow lists
- TgCalls: group calls, P2P calls, conference calls, screen share/presentation, audio and video
- Payments: invoices, plus shipping and pre-checkout query handling
- Mini apps: open and manage Telegram mini app sessions
- Translation & transcription: built-in message translation and voice-to-text
- Statistics: channel and supergroup growth, views, and activity
- Raw API: full TL coverage via client.invoke()
- Python cross-lang: native performance with a clean Python API
Bring calls into it too
TgCalls extends the same client with voice and video calling, no separate stack to learn.
TgCalls
An elegant Rust client for Telegram voice and video calls.
Bring voice and video calling to your Telegram applications. Join group calls, stream audio or video, and build direct P2P and conference calls with a clean Rust API, built on ferogram and powered by ntgcalls.
let calls = Calls::new(client); calls.play(chat_id, "song.mp3").await?;
The simplest way to play audio in a group call, Calls API handles join, voice-chat creation, and media detection for you.
let calls = Calls::new(client); calls.play(chat_id, "song.mp3").await?;
use tgcalls::Calls; #[tokio::main] async fn main() -> anyhow::Result<()> { let mut args = std::env::args().skip(1); let chat_id: i64 = args .next() .expect("usage: simple_calls <chat_id> <file>") .parse()?; let path = args.next().expect("missing audio file path"); let api_id: i32 = std::env::var("API_ID")?.parse()?; let api_hash = std::env::var("API_HASH")?; let (client, shutdown) = ferogram::Client::quick_connect("tgcalls.session", api_id, &api_hash).await?; let calls = Calls::new(client); calls.play(chat_id, path).await?; println!("Playing. Press Ctrl+C to stop."); tokio::signal::ctrl_c().await?; calls.leave(chat_id).await?; drop(shutdown); Ok(()) }
The ecosystem
Repositories
Three repos, one workspace. Star them, fork them, open a PR.