vaegram
A Telegram MTProto client in Rust, for bots and user accounts
Documentation • Examples • Releases
use *;
async
vaegram talks to Telegram's main API over MTProto, the protocol the official apps use. A bot can use it in place of the Bot API, and a user account can use it as a custom client. The transport, encryption and session are written from scratch in Rust, and the types for every function of API layer 233 are generated from Telegram's schema.
Features
- Bot login with a token, and user login with a phone code, a 2FA password or a QR code.
on_*handlers and hooks, with filters you combine with&,|and!.- Conversations with
ask,listen,wait_for_clickand next-step handlers. - Friendly methods for chats, messages, media, stories, payments, gifts and business accounts, and
invokefor any raw function. - HTML widgets over MTProto: bots send widgets and answer queries; user accounts read widgets, send queries and poll shared data. Shared-widget copies retain their id. Rendering HTML requires a host application.
- A session file that keeps the login, the chats the client has seen and the update state, so a restart picks up the updates it missed. SQLite, redb, PostgreSQL, Redis, MongoDB, S3 and Vault storage come behind cargo features.
- Transfers that survive a dead connection, a server error or a FLOOD_WAIT. Uploads, and downloads of a file whose size is known, go over several connections, and of those a bot's transfers of 8 MiB or more are paced at what Telegram allows a bot (about 20 MB/s each way, measured with one bot; chunks served by a CDN are not paced).
- Rate limiting, FLOOD_WAIT retries, and reconnects that fill update gaps.
- An observer for every request, events for failures, and recorded traffic you can replay in tests.
- Crypto from WarpCrypto.
Installing
[]
= "0.3"
= { = "1", = ["macros", "rt-multi-thread"] }
vaegram needs Rust 1.85 or newer. The vae crate is the same library under a shorter name: vae = "0.3", then
use vae::Client;.
Get an api_id and api_hash from my.telegram.org. A bot also needs a token from
@BotFather.
Logging in as a user
Leave out .bot_token(..) and start() asks for the phone number, the login code and the 2FA password:
let app = builder.start.await?;
let me = app.get_me.await?;
println!;
app.send_message.await?;
Examples
Buttons and callback queries (examples/demo_bot.rs):
app.on_message;
app.on_callback_query;
A question and its answer:
app.on_message;
Raw API calls and Telegram errors:
use functions;
let config = app.invoke.await?;
match app.send_message.await
Chat ids follow the Bot API: users are positive, groups negative, and channels start with -100. A method that takes
a chat also accepts "me", "@username", a t.me link, or a &Chat, &User or &Message.
Sessions
The first run logs in and writes my_bot.session, and later runs reuse it. One client at a time can open a session
file. .in_memory() keeps nothing on disk, .storage_engine(..) stores the session anywhere, and
export_session_string() puts the login in a single line for an environment variable.
A session file or string is the login itself. Anyone who has it is logged in as that account, so never commit or share it.
Testing offline
.record("bot.rec") writes everything a client sends and receives, and session::Replay serves that file back on
localhost. Your handlers then run against real Telegram traffic with no network or credentials.
examples/replay_test.rs shows the whole loop.
Development
License
Apache-2.0. Use it, fork it, change it, ship it. Every copy and fork must keep the NOTICE file crediting vaegram and Riajul, and may not use the vaegram or vae name to promote itself.