ferogram

ferogram is an async Rust library for Telegram’s MTProto protocol. It works for user accounts and bots, and talks to Telegram directly over MTProto with no Bot API HTTP proxy in the middle.

Everything in the workspace is written from scratch: the .tl schema parser, the TL code generator, AES-IGE crypto, the DH key exchange, MTProto framing, the session layer, and the high-level client on top. Each piece is its own crate so you can pull in just what you need.

Why it exists

I was already using other MTProto libraries and kept running into cases where I needed things to work a bit differently than they allowed. So I wrote my own.

The goal was to cover the major use cases first, and it does. If something’s missing for you, drop by t.me/FerogramChat. I genuinely like hearing what people are building with it.

Crates

Most people only need ferogram. But each crate is independently published if you need a specific layer on its own.

The rough dependency chain:

ferogram
└ ferogram-mtsender
  └ ferogram-connect
    ├ ferogram-mtproto
    │ ├ ferogram-tl-types
    │ │ └ (build) ferogram-tl-gen
    │ │   └ (build) ferogram-tl-parser
    │ └ ferogram-crypto
    └ ferogram-crypto

Quick install

[dependencies]
ferogram = "0.5.0"
tokio    = { version = "1", features = ["full"] }

Get api_id and api_hash from my.telegram.org. That’s all you need to get started.

Where to go next

• Installation covers credentials, optional feature flags, and session backends.
• Quick Start: Bot gets a bot running in about 20 lines.
• Quick Start: User Account covers phone login and sending your first message.
• Crate Architecture if you want to understand how the pieces fit together.

Python

Python support is live via ferogram-py. Pre-built wheels, no Rust toolchain needed.

pip install ferogram

Community

• Channel (releases, announcements): t.me/Ferogram
• Chat (questions, discussion): t.me/FerogramChat
• API docs: docs.rs/ferogram
• GitHub: github.com/ankit-chaubey/ferogram

License

MIT OR Apache-2.0.

Usage must comply with Telegram’s API Terms of Service.

Release History

ferogram started as a renamed continuation of layer v0.5.0. Every release since then has been a proper source release with a tagged version and a changelog entry.

v0.5.0

Released 2026-05-16. API consolidation release. Paired functions that differed only by a single boolean condition have been merged into one. Download and upload paths were redesigned around AsyncRead/AsyncWrite. No new protocol or behavioural changes.

Breaking changes

Merged paired functions into one

Download and upload API redesigned

Old API passed raw InputFileLocation handles. New API works directly with &MessageMedia:

#![allow(unused)]
fn main() {
// download to any AsyncWrite sink
client.download(msg.media().unwrap(), &mut file).await?;

// download to disk
client.download_file(msg.media().unwrap(), "photo.jpg").await?;

// lazy chunk iterator
let mut iter = client.iter_download(msg.media().unwrap()).unwrap();
while let Some(chunk) = iter.next().await? { ... }

// upload from any AsyncRead
let uploaded = client.upload(reader, "file.jpg").await?;

// upload from path (stats file, streams to upload)
let uploaded = client.upload_file_from_path("photo.jpg").await?;
}

IncomingMessage also gains two convenience methods:

#![allow(unused)]
fn main() {
msg.download(&mut buf).await?;   // stream to AsyncWrite
let bytes = msg.bytes().await?;  // into Vec<u8>
}

set_profile is now a builder

#![allow(unused)]
fn main() {
// user
client.set_profile("me").name("Alice", "").bio("Hello!").send().await?;

// channel / group
client.set_profile("@mychannel").title("New Name").bio("About text").send().await?;
}

stats returns ChannelStats

#![allow(unused)]
fn main() {
match client.stats("@mychannel").await? {
    ChannelStats::Broadcast(s) => { /* channel */ }
    ChannelStats::Megagroup(s) => { /* supergroup */ }
}
}

Upload part-size table revised

Five tiers keyed on file size (< 1 MB, 1-32 MB, 32-512 MB, 512 MB-1 GB, > 1 GB) replace the old two-tier heuristic. This reduces per-chunk overhead for small files and stays safely below the 4000-part hard limit for large ones.

Upgrading from 0.4.1

ferogram = "0.5.0"

Rename call sites per the table above. The session format, feature flags, and all other APIs are unchanged.

v0.4.1

Released 2026-05-14. Patch on top of 0.4.0: one new API for faster onboarding, a configurable update buffer, session schema improvements, and 15 new examples. No breaking changes.

Client::quick_connect

One call handles the builder, connection, and the full auth flow from stdin. Returns immediately if the session is already authorized.

#![allow(unused)]
fn main() {
use ferogram::Client;

const API_ID: i32 = 12345;
const API_HASH: &str = "your_api_hash";

let (client, _shutdown) = Client::quick_connect("bot.session", API_ID, API_HASH).await?;
}

Bot tokens are detected automatically by their <digits>:<string> shape, so the same call works for both bots and users.

If you need an option quick_connect does not expose (proxy, PFS, custom transport, catch-up), switch to Client::builder(). The session file is compatible.

See quick_connect reference for the full signature and error table.

Configurable update buffer

Two new builder methods let you tune the user-facing dispatch queue. Internal MTProto state (pts, qts, getDifference) is unaffected; only the Update queue from stream_updates() is governed here.

#![allow(unused)]
fn main() {
use ferogram::{Client, update_config::OverflowStrategy};

let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .update_queue_capacity(512)
    .update_overflow_strategy(OverflowStrategy::DropOldest)
    .connect().await?;
}

DropOldest (default) evicts ephemeral updates (typing, online status) first, then the oldest normal update, keeping the incoming one. DropNewest discards the incoming update instead. Default capacity is 2048.

For memory-constrained hosts (Termux, small VPS) there is a shortcut:

#![allow(unused)]
fn main() {
Client::builder()
    // ...
    .low_memory_mode(true)  // 256-slot queue, DropOldest
    .connect().await?;
}

Session schema migration

Two additions to the SQLite/LibSQL schema, applied automatically when the database is opened. Both are no-ops on a fresh database.

• peers table gains an is_chat column for tracking basic groups.
• New min_peers table stores min-user message contexts needed for InputPeerUserFromMessage.

Existing session files migrate automatically.

Periodic session save

The client now writes a full session snapshot (peers, channel_pts, min_peers, DC auth/salt data) to the session backend every 60 seconds whenever the peer cache has been mutated since the last save. A final save runs unconditionally on shutdown. Previously peers were only written on explicit save_session() calls, so a crash between calls could lose recently seen peers.

Salt expiry fix past 2038

valid_until in future salts was stored as i32. Telegram sends validity windows that extend into the 2050s. Those values overflow i32 and wrap negative, making every salt look expired on a signed comparison and causing constant re-fetches. Changed to u32 throughout.

GuestChatAnswer return type corrected

GuestChatAnswer::send now returns InputBotInlineMessageID matching the actual TL schema. The setBotGuestChatResult constructor ID was also wrong in the previous schema; both are fixed. If you were pattern-matching on the old bool return, update your call sites.

New type and methods

• ParticipantStatus is now exported from the crate root.
• User::bot_guestchat() returns true if the bot supports guest-chat mode.
• GuestChatQuery::via_from() returns the original requester peer when Telegram includes guestchat_via_from in the message.

15 new examples

All examples live under ferogram/examples/.

Userbot tools: admin_log, chat_history, dialogs_list, download_media, get_participants, schedule_message, search_messages, serverless_userbot, string_session_gen.

Bots: echo_bot, filters_showcase, hello_self, inline_keyboard, inline_query_bot, poll_bot, translate_bot.

Upgrading from 0.4.0

ferogram = "0.4.1"

No API changes required. The session migration is automatic.

[0.4.0]: 2026-05-08

0.4.0 is the first production-ready release of ferogram. It ships Layer 225 support and a reworked poll API. All users are advised to upgrade to 0.4.0 (or 0.4.x+) as the most recommended and supported version.

If you run into any bugs, please open an issue on GitHub or reach us at @FerogramChat. Thank you for using ferogram!

For the latest git revision: https://github.com/ankit-chaubey/ferogram

Note: 0.3.9 was a broken publish. The workspace internal deps were not bumped so crates.io resolved ferogram-tl-types to the old Layer 224 build. 0.4.0 fixes that and is the correct release to use.

v0.3.9

Released 2026-05-07. Updated to TL Layer 225. Poll builder overhaul, guest-chat support for bots, two new client methods, and full MarkdownV2/HTML spec compliance in the parsers.

send_poll now takes PollBuilder (breaking)

The old flat signature (question, answers, quiz, correct_index, multiple_choice) is gone. Pass a PollBuilder instead:

#![allow(unused)]
fn main() {
use ferogram::PollBuilder;

client.send_poll(peer,
    PollBuilder::new("Favourite runtime?")
        .answers(["Tokio", "async-std", "smol"])
        .public_voters(true)
        .close_period(300)
).await?;

// Quiz with answer explanation
client.send_poll(peer,
    PollBuilder::new("Capital of France?")
        .answers(["Berlin", "Paris", "Rome"])
        .quiz(true)
        .correct_index(1)
        .solution("It's Paris.")
        .hide_results_until_close(true)
).await?;
}

New fields the old API did not expose: public_voters, shuffle_answers, hide_results_until_close, close_period, close_date, solution, subscribers_only, countries_iso2.

Guest-chat queries (bots only)

A new Update::GuestChatQuery variant handles updateBotGuestChatQuery. Fires when a user invites the bot into a guest-chat context. GuestChatQuery derefs to IncomingMessage and carries query_id, message, reference_messages, and qts.

Answer with the GuestChatAnswer builder:

#![allow(unused)]
fn main() {
if let Update::GuestChatQuery(q) = update {
    q.answer()
        .article("My result")
        .text("The answer")
        .send(&client)
        .await?;
}
}

Supported result kinds: article, photo, document, game, location, venue, contact, webpage, invoice, raw. Sends via messages.setBotGuestChatResult.

New client methods

delete_reaction(peer, msg_id, participant) reports and removes a specific user’s reaction on a message. Returns true on success.

get_poll_stats(peer, msg_id) returns detailed vote stats for a poll. Returns tl::types::stats::PollStats.

BannedRights::send_reactions

New field on the ban-rights builder:

#![allow(unused)]
fn main() {
BannedRights::default().send_reactions(false)
}

MarkdownV2 and HTML parser update (ferogram-parsers)

parse_markdown and generate_markdown now implement the full Telegram Bot API MarkdownV2 spec. The main breaking change: __text__ is Underline now, not Italic. If you relied on the old behaviour, call parse_markdown_v1 explicitly (deprecated, removed in 0.4.0).

Explicit aliases added: parse_markdown_v2, generate_markdown_v2.

HTML: added <ins> as underline, <span class="tg-spoiler"> as spoiler, <blockquote>/<blockquote expandable> for block quotes, <tg-time unix="N"> for formatted dates. The <pre><code class="language-X"> bug that produced two entities instead of one is fixed. generate_html emits all of the above.

Upgrading from 0.3.8

ferogram = "0.3.9"

Two things to fix: send_poll call sites (see above), and any markdown that relied on __text__ being Italic (change to _text_).

v0.3.8

Released 2026-05-06. A small patch release fixing two broken APIs from 0.3.7.

send_to_self is fixed

In 0.3.7 the function body got swapped during a refactor. Calling send_to_self(msg) was silently hitting the wrong code path. It now correctly sends to your Saved Messages using messages.sendMessage with InputPeer::PeerSelf, and returns the sent message as before.

open_mini_app is now public

open_mini_app(peer, MiniApp) was accidentally left private in 0.3.7. It’s pub now. Supports all four mini-app types: Main, Url, App, and Simple.

get_chat_full is now public

Was pub(crate) before. Now pub, so you can call it directly if you need the raw full chat info without going through a helper.

v0.3.7

Released 2026-05-05. Workspace restructure, three new crates, and a handful of API cleanups.

New crates

Three crates were extracted this release. The main ferogram crate re-exports everything from them, so if you’re not doing anything low-level, your code doesn’t need to change.

ferogram-connect is now a real crate instead of a throwaway demo binary. It owns the raw TCP connection layer, MTProto framing, transport negotiation (Intermediate, Obfuscated, FakeTLS), SOCKS5, and proxy support. Useful if you want to build something that speaks MTProto without pulling in the full client.

ferogram-fsm packages the FSM layer (FsmState, StateContext, StateStorage, MemoryStorage) as a standalone crate that can be versioned and published on its own.

ferogram-mtsender does the same for the sender pool and retry policy. RetryPolicy, AutoSleep, CircuitBreaker, NoRetries all live here now.

The old ferogram-app and ferogram-bot example binaries were removed. They’ve been replaced by examples inside ferogram/examples/.

Getting a peer’s ID with .bare_id()

You used to need a full match to pull a numeric ID out of a tl::enums::Peer. Now there’s PeerExt:

#![allow(unused)]
fn main() {
use ferogram::{PeerExt, OptionPeerExt};

// any Peer variant → i64
let id = peer.bare_id();

// works on Option<&Peer> too, no .map() needed
let sender = msg.sender_id().bare_id(); // Option<i64>
let chat   = msg.peer_id().bare_id();   // Option<i64>
}

The name bare_id is intentional: it gives you the native Telegram ID, not the Bot-API-encoded one. A channel with native ID 1234567890 is -1001234567890 in the Bot API.

PeerCache and ExperimentalFeatures are public

PeerCache is now in its own file and fully public. It’s what handles every peer lookup: user hashes, channel hashes, basic groups, min-users, the username index, the phone index. You can read from it directly if you need low-level access.

ExperimentalFeatures lets you opt into behaviours that deviate from strict Telegram spec. The main flag is allow_zero_hash, which lets bots skip needing a cached access hash (don’t use this on user accounts):

#![allow(unused)]
fn main() {
Client::builder()
    .experimental_features(ExperimentalFeatures {
        allow_zero_hash: true,
        ..Default::default()
    })
    .connect().await?;
}

Breaking changes

download_media_to_file is now download_file:

#![allow(unused)]
fn main() {
// before
client.download_media_to_file(location, &path).await?;

// now
client.download_file(location, &path).await?;
}

forward_messages now takes a fourth argument:

#![allow(unused)]
fn main() {
// before
client.forward_messages(dest, &[id], src).await?;

// now
client.forward_messages(dest, &[id], src, ForwardOptions::default()).await?;
}

respond_ex is gone. respond already accepts InputMessage, so it was redundant:

#![allow(unused)]
fn main() {
// before
msg.respond_ex(InputMessage::html("<b>hi</b>")).await?;

// now
msg.respond(InputMessage::html("<b>hi</b>")).await?;
}

Upgrading from 0.3.6

ferogram = "0.3.7"

The three breaking changes above need fixing. The rest is additive.

v0.3.6

Released 2026-04-30. API stabilization update towards v0.4.0.

Some APIs have been simplified, merged, or removed where redundant. This may require a one-time migration. The goal is a consistent, predictable API that does not need disruptive changes again.

Future updates will focus on new features and improvements.

See FEATURES.md for the full current API surface.

Upgrading from 0.3.5

ferogram = "0.3.6"

v0.3.5

Released 2026-04-30. Critical deserialization fix and update-state hardening.

PollResults deserialization fix

PollResults was incorrectly treated as a bare type throughout the codebase, meaning the 4-byte constructor ID was never read from the wire. The deserializer consumed that ID as the flags field instead, producing garbage flag values and misaligning every subsequent field read. Any getChannelDifference or getDifference response that contained a poll message would fail with an unexpected constructor id error and drop the entire update batch.

The fix routes PollResults through crate::enums::PollResults like every other boxed type, so the constructor ID is read and validated before fields are deserialized. Both MessageMediaPoll.results and updateMessagePoll.results are affected.

getDifference self-deadlock fix

The reader_loop select arm that fires the MessageBoxes gap deadline was directly awaiting run_pending_differences(). Because reader_loop is the only task reading TCP frames, the getDifference RPC it sent could never receive a response, producing a 30-second hang after any gap detection. The fix spawns a separate task for the diff runner, matching the pattern already used by the keepalive arm. A diff_in_flight: AtomicBool guard prevents duplicate spawns while a diff is already in progress.

Lazy access-hash resolution

Channel access hashes are now resolved purely from incoming update entities and the persisted peer cache. The automatic GetDialogs call at startup and catch-up has been removed. This makes ferogram resilient to Telegram schema changes in dialog-related types without requiring a layer bump.

Client::warm_peer_cache_from_dialogs() is a new public opt-in method for cases where you need access hashes before any update has arrived for a channel. See Raw API Access for usage details.

Upgrading from 0.3.4

ferogram = "0.3.5"

No API changes required. The fix is automatic.

v0.3.4

Released 2026-04-28. MTProto hardening release: PFS temp-key sessions, access-hash prefetch on startup, and safer deserialization across the board.

PFS (Perfect Forward Secrecy)

A new .pfs(true) method on ClientBuilder enables Perfect Forward Secrecy at the transport layer. When set, the DC pool performs a temporary DH key bind immediately after the permanent auth key is established. The connection then runs under a short-lived session key derived from that bind; the permanent key is never used to encrypt traffic directly. If the bind RPC fails for any reason the pool falls back to the standard session without disrupting the connection.

Access-hash prefetch

prefetch_channel_access_hashes is now called automatically at startup and after every catch-up cycle. It issues a single GetDialogs request and caches all returned channel and user access hashes before the first live update is dispatched. In practice this eliminates the CHANNEL_INVALID errors that previously appeared on reconnects when an incoming update referenced a channel the in-memory cache had not yet seen.

from_bytes_exact

Deserializable::from_bytes_exact is a new method available on all TL types. It wraps the common Cursor::from_slice + deserialize pattern and additionally returns an error if any bytes remain unconsumed after deserialization. All call sites across lib.rs, dc_pool.rs, and pts.rs have been migrated to it. Parse failures on incoming Updates frames are now logged as warnings instead of being silently discarded.

Concurrent get_difference fix

Previously, if two tasks raced to call get_difference at the same time, the second would return immediately with an empty result and potentially miss a fill cycle. It now polls every 50 ms waiting for the in-flight call to finish, and gives up after 35 s with a warning so the next gap tick can retry rather than hanging indefinitely.

Upgrading from 0.3.3

ferogram = "0.3.4"

To enable PFS:

#![allow(unused)]
fn main() {
let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_hash")
    .session("bot.session")
    .pfs(true)
    .connect()
    .await?;
}

v0.3.3

Released 2026-04-22. Bot framework release: composable filters, finite state machine, middleware pipeline, conversation API, and a new proc-macro crate.

ferogram-derive

A new ferogram-derive crate adds the #[derive(FsmState)] proc-macro. Applying it to a unit-variant enum generates as_key and from_key implementations automatically. The crate is gated behind a derive feature flag and FsmState is re-exported from the crate root, so the only import you need is use ferogram::FsmState.

Filters

ferogram::filters provides composable, synchronous predicates over IncomingMessage. Built-in constructors cover the common cases: command, private, text, media, and others. Predicates compose with &, |, and ! operators, so you can express things like command("start") & private() directly in the handler registration. Filters also integrate with the FSM via StateContext, letting you gate handlers on the current conversation state.

FSM

ferogram::fsm provides the full finite state machine layer: the FsmState trait, StateContext, StateKey, StateKeyStrategy, and StateStorage. The default storage is an in-memory DashMap-backed store keyed by peer. Custom backends can be plugged in via an async-trait extension point, so SQLite or Redis-backed stores are easy to add. A new examples/order_bot.rs walks through a multi-step order flow driven by the FSM.

Middleware

ferogram::middleware adds a Middleware trait and a Next chain that wraps every handler dispatch. The crate ships a ready-to-use rate-limit middleware backed by DashMap. DispatchError and DispatchResult are exported for use in custom middleware.

Conversation

ferogram::conversation provides a Conversation type for sequential, stateful exchanges with a single peer. It wraps an UpdateStream scoped to the conversation lifetime and transparently buffers updates arriving from other peers during the exchange.

IncomingMessage helpers

IncomingMessage gained a full set of inspection methods: chat_id, is_private, is_group, is_channel, is_any_group, from_id, is_bot_command, command, is_command_named, command_args, has_media, has_photo, has_document, is_forwarded, is_reply, and album_id.

New update types

Eight new update types are now exported from the crate root: ParticipantUpdate, JoinRequestUpdate, MessageReactionUpdate, PollVoteUpdate, BotStoppedUpdate, ShippingQueryUpdate, PreCheckoutQueryUpdate, and ChatBoostUpdate.

New API method

Client::get_chat_administrators() returns all admins and the creator for a channel or supergroup. For basic groups it returns all participants; use the is_admin field on the result to distinguish.

New documentation pages

Bot Framework: Middleware & Dispatcher, Finite State Machine (FSM), Conversation API. API reference: Bot Configuration, Stats & Analytics.

Upgrading from 0.3.2

ferogram = "0.3.3"

To use #[derive(FsmState)]:

ferogram = { version = "0.3.3", features = ["derive"] }

v0.3.2

Released 2026-04-21. Correctness and session-save hardening.

SeenMsgIds

The SeenMsgIds deque is now paired with a HashSet so duplicate checks under concurrent workers are O(1) instead of O(n). On busy connections receiving many server messages simultaneously this removes a hot path that was linear in the deque length.

Session save race

Session temp files now get a unique name per write, and a write_lock serializes concurrent saves. Previously two concurrent saves could race on the rename step, which caused data loss on Windows. Both are now safe.

Bug fixes

Five correctness bugs were patched:

The PaddedIntermediate handshake was not being sent on DC pool worker connections. Without it the server would silently drop or misparse every frame from those connections.

new_session_created was resetting the session on fresh connections even when it should not, which caused a session ID mismatch on every subsequent decrypt.

scan_body was passing None as sent_msg_id during container iterations, letting stale cached results overwrite live responses from the server.

The importAuthorization branch condition was inverted, so the import was skipped precisely in the cases where it was required and ran in cases where it was not.

Server 4-byte transport error codes received during the DH handshake are now surfaced properly instead of being misclassified as “plain frame too short”.

v0.3.1

Released 2026-04-20. Patch release fixing the docs.rs build. No functional changes from 0.3.0.

Upgrading from 0.3.0

ferogram = "0.3.1"

v0.3.0

Released 2026-04-19. The biggest release so far: two new crates, a redesigned connection stack, CDN file download support, and a much larger API reference.

Two new crates

ferogram-session takes over all session persistence. It owns PersistedSession, DcEntry, DcFlags, UpdatesStateSnap, CachedPeer, CachedMinPeer, default_dc_addresses, and all storage backends: BinaryFileBackend, InMemoryBackend, StringSessionBackend, SqliteBackend, and LibSqlBackend. The main ferogram crate re-exports everything from it, so existing code needs no changes.

ferogram-parsers takes over Telegram entity parsing. It provides parse_markdown, generate_markdown, parse_html, and generate_html. An optional html5ever feature swaps in a spec-compliant HTML5 tokenizer. The main ferogram::parsers module re-exports these, so again, nothing changes for most users.

Both crates can also be used as standalone dependencies if you only need the session or parser layer without the full client.

Session format

The binary session format moved to version 5. It now persists the home DC, the full DC table with per-DC auth keys and flags, update state (pts, qts, date, seq), per-channel pts values, the peer access-hash cache, and min-user message contexts for InputPeerUserFromMessage. Older session files still load without error. Saves are atomic: written to a .tmp file first, then renamed into place, so a crash during save cannot corrupt the session. DC flags are now persisted, which means media and CDN DC entries survive restarts.

Connection options

ClientBuilder gained three new methods.

.probe_transport(true) races Obfuscated, Abridged, and HTTP transports at connect time and uses whichever one succeeds first. Useful on networks where one transport is throttled or blocked. Has no effect when MTProxy is configured.

.resilient_connect(true) adds two fallback layers when direct TCP fails. First it tries DNS-over-HTTPS, querying both Google DoH and Mozilla/Cloudflare DoH. If that also fails, it tries Telegram’s Firebase/Google special-config endpoint to get working DC addresses. Intended for restricted networks where normal TCP and DNS are both unreliable.

.experimental_features(...) accepts an ExperimentalFeatures struct with three fields: allow_zero_hash, allow_missing_channel_hash, and auto_resolve_peers (reserved, not yet active).

CDN downloads

A new ferogram::cdn_download module handles the full Telegram CDN file path. It requests chunks via upload.getCdnFile, re-uploads stale chunks via upload.reuploadCdnFile, and decrypts each chunk with AES-256-CTR using the key and IV provided by Telegram. Exports CdnDownloader, CdnChunkResult, and CDN_CHUNK_SIZE. Used internally when large files are served from a CDN DC rather than the main DC.

DNS-over-HTTPS and special-config

ferogram::dns_resolver queries Google DoH and Mozilla/Cloudflare DoH, merges IPv4 and IPv6 answers, and caches results by TTL.

ferogram::special_config implements Telegram’s last-resort fallback: decodes the encrypted response from Telegram’s Firebase/Google endpoint and extracts DC addresses from help.configSimple.

MTProto internals

ferogram-mtproto gained a bind_temp_key module and now re-exports encrypt_bind_inner, gen_msg_id, serialize_bind_temp_auth_key, EncryptedSession, SeenMsgIds, and new_seen_msg_ids. Primarily useful for library authors working at the MTProto layer directly.

New documentation pages

Advanced: CDN Downloads, Transport Probing and Resilient Connect, Connection Restart Policy, Experimental Features.

API reference: ClientBuilder, Types Reference, Chat Management, Contacts and Blocking, Forum Topics, Games and Payments, Invite Links, Polls and Votes, Privacy and Notifications, Profile and Account, Stickers.

Upgrading from 0.2.0

ferogram = "0.3.0"

No API changes required. If you want to use the new connection options:

#![allow(unused)]
fn main() {
let client = Client::builder()
    .probe_transport(true)
    .resilient_connect(true)
    .connect()
    .await?;
}

v0.2.0

Released 2026-04-13. Focused on concurrency, protocol correctness, and transport hardening.

Concurrency

The peer cache moved from RwLock<HashMap> to a moka concurrent cache, removing lock contention during peer lookups. The pending RPC map was replaced with DashMap for lock-free response routing. The DC pool switched from parking_lot::Mutex to tokio::sync::Mutex so it no longer blocks the async runtime during DC operations.

Protocol correctness

Fresh DH sessions now wait 2 seconds after key derivation to allow Telegram to propagate the new auth key across DCs before the first request is sent. Stale key detection was simplified: only error -404 triggers key rotation now. getDifference deserialization tolerates unknown server responses instead of failing and dropping buffered updates. Container message parsing validates inner message alignment and safely discards malformed frames.

Transport

FakeTLS transport now prepends the Change Cipher Spec record to the first application data chunk, matching the TLS handshake pattern Telegram expects. Transport errors -429 and -444 are now logged clearly before reconnecting rather than failing silently.

v0.1.0

Released 2026-04-11. The initial release of ferogram, renamed and rebranded from layer v0.5.0.

Proxy and transport

Full MTProxy support via t.me/proxy or tg://proxy links, or manually with host, port, and secret. PaddedIntermediate transport (0xDD secrets) adds randomized padding to blend in with official Telegram client traffic. FakeTLS transport (0xEE secrets) wraps MTProto in TLS-like framing. SOCKS5 proxy with optional username and password. IPv6 connectivity for both Telegram DCs and proxy connections.

Session backends

Binary file, in-memory, string/base64, SQLite, and libSQL.

Protocol fixes

Auth key generation now uses the correct PQInnerDataDc constructor with the DC id included, resolving auth failures on many DCs. Incoming message validation uses a rolling buffer of the last 500 server msg_id values plus a 300 second timestamp window to prevent replay attacks. DH step 3 retry (dh_gen_retry) retries with cached params for up to 5 attempts, matching Telegram Desktop behavior. MTProxy connections now correctly route through the proxy host instead of going directly to Telegram DCs. getChannelDifference starts at limit 100 and increases to 1000 on subsequent calls.

See the full CHANGELOG for the raw entry format.

Installation

Add to Cargo.toml

[dependencies]
ferogram = "0.5.0"
tokio        = { version = "1", features = ["full"] }

ferogram re-exports everything you need for both user clients and bots.

Getting API credentials

Every Telegram API call requires an api_id (integer) and api_hash (hex string) from your registered app.

Step-by-step:

1. Go to https://my.telegram.org and log in with your phone number
2. Click API development tools
3. Fill in any app name, short name, platform (Desktop), and URL (can be blank)
4. Click Create application
5. Copy App api_id and App api_hash

SECURITY: Never hardcode credentials in source code. Use environment variables or a secrets file that is in .gitignore.

#![allow(unused)]
fn main() {
// Good: from environment
let api_id:   i32    = std::env::var("TG_API_ID")?.parse()?;
let api_hash: String = std::env::var("TG_API_HASH")?;

// Bad: hardcoded in source
let api_id   = 12345;
let api_hash = "deadbeef..."; // ← never do this in a public repo
}

Bot token (bots only)

For bots, additionally get a bot token from @BotFather:

1. Open Telegram → search @BotFather → /start
2. Send /newbot
3. Choose a display name (e.g. “My Awesome Bot”)
4. Choose a username ending in bot (e.g. my_awesome_bot)
5. Copy the token: 1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ

Optional features

SQLite session storage

ferogram = { version = "0.5.0", features = ["sqlite-session"] }

Stores session data in a SQLite database instead of a binary file. Better choice for long-running servers where crash-corruption of the binary file is a concern.

LibSQL / Turso session storage: New in v0.2.0

ferogram = { version = "0.5.0", features = ["libsql-session"] }

Backed by libsql: supports local embedded databases and remote Turso cloud databases. Ideal for serverless or distributed deployments.

#![allow(unused)]
fn main() {
use ferogram::session_backend::LibSqlBackend;

// Local
let backend = LibSqlBackend::open_local("session.libsql").await?;

// Remote (Turso cloud)
let backend = LibSqlBackend::open_remote(
    "libsql://your-db.turso.io",
    "your-turso-auth-token",
).await?;
}

String session (portable, no extra deps): New in v0.2.0

No feature flag needed. Encode a session as a base64 string and restore it anywhere:

#![allow(unused)]
fn main() {
// Export
let s = client.export_session_string().await?;

// Restore
let (client, _shutdown) = Client::builder()
    .api_id(api_id)
    .api_hash(api_hash)
    .session_string(s)
    .connect()
    .await?;
}

See Session Backends for the full guide.

HTML entity parsing

# Built-in hand-rolled HTML parser (no extra deps)
ferogram = { version = "0.5.0", features = ["html"] }

# OR: spec-compliant html5ever tokenizer (overrides built-in)
ferogram = { version = "0.5.0", features = ["html5ever"] }

Raw type system features (ferogram-tl-types)

If you use ferogram-tl-types directly for raw API access:

ferogram-tl-types = { version = "0.5.0", features = [
    "tl-api",          # Telegram API types (required)
    "tl-mtproto",      # Low-level MTProto types
    "impl-debug",      # Debug trait on all types (default ON)
    "impl-from-type",  # From<types::T> for enums::E (default ON)
    "impl-from-enum",  # TryFrom<enums::E> for types::T (default ON)
    "name-for-id",     # name_for_id(u32) -> Option<&'static str>
    "impl-serde",      # serde::Serialize / Deserialize
] }

Verifying installation

use ferogram_tl_types::LAYER;

fn main() {
    println!("Using Telegram API Layer {}", LAYER);
    // → Using Telegram API Layer 225
}

Platform notes

Quick Start: User Account

A complete working example: connect, log in, send a message to Saved Messages, and listen for incoming messages.

use ferogram::Client;
use ferogram::update::Update;

const API_ID: i32 = 0; // from https://my.telegram.org
const API_HASH: &str = ""; // from https://my.telegram.org

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _shutdown) = Client::quick_connect("my.session", API_ID, API_HASH).await?;

    // Send a message to yourself
    client.send_to_self("Hello from ferogram! 👋").await?;
    println!("Message sent to Saved Messages");

    // Stream incoming updates
    println!("Listening for messages… (Ctrl+C to quit)");
    let mut updates = client.stream_updates();

    while let Some(update) = updates.next().await {
        match update {
            Update::NewMessage(msg) if !msg.outgoing() => {
                let text   = msg.text().unwrap_or("(no text)");
                let sender = msg.sender_id()
                    .map(|p| format!("{p:?}"))
                    .unwrap_or_else(|| "unknown".into());

                println!("📨 [{sender}] {text}");
            }
            Update::MessageEdited(msg) => {
                println!("✏️  Edited: {}", msg.text().unwrap_or(""));
            }
            _ => {}
        }
    }

    Ok(())
}

Run it

cargo run

Fill in API_ID and API_HASH at the top of the file before running. On first run you’ll be prompted for your phone number and the code Telegram sends. On subsequent runs the session is reloaded from my.session and login is skipped automatically.

What each step does

For the full auth flow broken down step by step, see User Login.

Next steps

• User Login: full guide
• Two-Factor Auth (2FA)
• Session Backends: string sessions, SQLite, Turso
• Update Types

Quick Start: Bot

A working bot with commands, callback queries, and inline mode. Each update runs in its own task so the loop never blocks.

use ferogram::{Client, InputMessage, parsers::parse_markdown, update::Update};
use ferogram_tl_types as tl;
use std::sync::Arc;

const API_ID: i32 = 0; // from https://my.telegram.org
const API_HASH: &str = ""; // from https://my.telegram.org

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _shutdown) = Client::quick_connect("bot.session", API_ID, API_HASH).await?;
    let client = Arc::new(client);

    let me = client.get_me().await?;
    println!("✅ @{} is online", me.username.as_deref().unwrap_or("bot"));

    let mut updates = client.stream_updates();

    while let Some(update) = updates.next().await {
        let client = client.clone();
        // Each update in its own task: the loop never blocks
        tokio::spawn(async move {
            if let Err(e) = dispatch(update, &client).await {
                eprintln!("Handler error: {e}");
            }
        });
    }

    Ok(())
}

async fn dispatch(
    update: Update,
    client: &Client,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {

    match update {
        // Commands
        Update::NewMessage(msg) if !msg.outgoing() => {
            let text = msg.text().unwrap_or("").trim().to_string();

            if !text.starts_with('/') { return Ok(()); }

            let cmd = text.split_whitespace().next().unwrap_or("");
            let arg = text[cmd.len()..].trim();

            match cmd {
                "/start" => {
                    let (t, e) = parse_markdown(
                        "👋 **Hello!** I'm built with **ferogram**: async Telegram MTProto in Rust 🦀\n\n\
                         Use /help to see all commands."
                    );
                    msg.reply(InputMessage::text(t).entities(e)).await?;
                }
                "/help" => {
                    let (t, e) = parse_markdown(
                        "📖 **Commands**\n\n\
                         /start: Welcome message\n\
                         /ping: Latency check\n\
                         /echo `<text>`: Repeat your text\n\
                         /upper `<text>`: UPPERCASE\n\
                         /lower `<text>`: lowercase\n\
                         /reverse `<text>`: esreveR\n\
                         /id: Your user and chat ID"
                    );
                    msg.reply(InputMessage::text(t).entities(e)).await?;
                }
                "/ping" => {
                    let start = std::time::Instant::now();
                    let sent = msg.respond("🏓 …").await?;
                    let ms = start.elapsed().as_millis();
                    let (t, e) = parse_markdown(&format!("🏓 **Pong!** `{ms} ms`"));
                    sent.edit(InputMessage::text(t).entities(e)).await?;
                }
                "/echo"    => { msg.reply(if arg.is_empty() { "Usage: /echo <text>" } else { arg }).await?; }
                "/upper"   => { msg.reply(arg.to_uppercase().as_str()).await?; }
                "/lower"   => { msg.reply(arg.to_lowercase().as_str()).await?; }
                "/reverse" => {
                    let rev: String = arg.chars().rev().collect();
                    msg.reply(rev.as_str()).await?;
                }
                "/id" => {
                    if let Some(peer) = msg.peer_id() {
                        let chat = match peer {
                            tl::enums::Peer::User(u)    => format!("User `{}`",    u.user_id),
                            tl::enums::Peer::Chat(c)    => format!("Group `{}`",   c.chat_id),
                            tl::enums::Peer::Channel(c) => format!("Channel `{}`", c.channel_id),
                        };
                        let (t, e) = parse_markdown(&format!("🪪 **Chat:** {chat}"));
                        msg.reply(InputMessage::text(t).entities(e)).await?;
                    }
                }
                _ => { msg.reply("❓ Unknown command. Try /help").await?; }
            }
        }

        // Callback queries
        Update::CallbackQuery(cb) => {
            match cb.data().unwrap_or("") {
                "help"  => { client.answer_callback_query(cb.query_id, Some("Send /help for commands"), false, None, 0).await?; }
                "about" => { client.answer_callback_query(cb.query_id, Some("Built with ferogram: Rust MTProto 🦀"), true, None, 0).await?; }
                _       => { client.answer_callback_query(cb.query_id, None, false, None, 0).await?; }
            }
        }

        // Inline mode
        Update::InlineQuery(iq) => {
            let q   = iq.query().to_string();
            let qid = iq.query_id;
            let results = vec![
                make_article("1", "🔠 UPPER", &q.to_uppercase()),
                make_article("2", "🔡 lower", &q.to_lowercase()),
                make_article("3", "🔄 Reversed", &q.chars().rev().collect::<String>()),
            ];
            client.answer_inline_query(qid, results, 30, false, None).await?;
        }

        _ => {}
    }

    Ok(())
}

fn make_article(id: &str, title: &str, text: &str) -> tl::enums::InputBotInlineResult {
    tl::enums::InputBotInlineResult::InputBotInlineResult(tl::types::InputBotInlineResult {
        id: id.into(), r#type: "article".into(),
        title: Some(title.into()), description: Some(text.into()),
        url: None, thumb: None, content: None,
        send_message: tl::enums::InputBotInlineMessage::Text(
            tl::types::InputBotInlineMessageText {
                no_webpage: false, invert_media: false,
                message: text.into(), entities: None, reply_markup: None,
            }
        ),
    })
}

Key differences: User vs Bot

Next steps

• Bot Login: full guide
• Callback Queries
• Inline Mode
• Inline Keyboards
• Admin & Ban Rights

User Login

User login happens in three steps: request code → submit code → (optional) submit 2FA password.

Just want something working? Client::quick_connect handles all three steps interactively in one call, including 2FA. This page covers the explicit step-by-step flow for non-interactive setups (reading from env vars, config files, custom prompts, etc.).

Step 1: Request login code

#![allow(unused)]
fn main() {
let token = client.request_login_code("+1234567890").await?;
}

This sends a verification code to the phone number via SMS or Telegram app notification. The returned LoginToken must be passed to the next step.

Step 2: Submit the code

#![allow(unused)]
fn main() {
match client.sign_in(&token, "12345").await {
    Ok(name) => {
        println!("Signed in as {name}");
    }
    Err(SignInError::PasswordRequired(password_token)) => {
        // 2FA is enabled: go to step 3
    }
    Err(e) => return Err(e.into()),
}
}

sign_in returns:

• Ok(String): the user’s full name, login complete
• Err(SignInError::PasswordRequired(PasswordToken)): 2FA is enabled, need password
• Err(e): wrong code, expired code, or network error

Step 3: 2FA password (if required)

#![allow(unused)]
fn main() {
client.check_password(password_token, "my_2fa_password").await?;
}

This performs the full SRP (Secure Remote Password) exchange. The password is never sent to Telegram in plain text: only a cryptographic proof is transmitted.

Save the session

After a successful login, always save the session so you don’t need to log in again:

#![allow(unused)]
fn main() {
client.save_session().await?;
}

Full example with stdin

#![allow(unused)]
fn main() {
use ferogram::{Client, Config, SignInError};
use std::io::{self, BufRead, Write};

async fn login(client: &Client) -> Result<(), Box<dyn std::error::Error>> {
    if client.is_authorized().await? {
        return Ok(());
    }

    print!("Phone number: ");
    io::stdout().flush()?;
    let phone = read_line();

    let token = client.request_login_code(&phone).await?;

    print!("Code: ");
    io::stdout().flush()?;
    let code = read_line();

    match client.sign_in(&token, &code).await {
        Ok(name) => println!("✅ Welcome, {name}!"),
        Err(SignInError::PasswordRequired(t)) => {
            print!("2FA password: ");
            io::stdout().flush()?;
            let pw = read_line();
            client.check_password(t, &pw).await?;
            println!("✅ 2FA verified");
        }
        Err(e) => return Err(e.into()),
    }

    client.save_session().await?;
    Ok(())
}

fn read_line() -> String {
    let stdin = io::stdin();
    stdin.lock().lines().next().unwrap().unwrap().trim().to_string()
}
}

Sign out

#![allow(unused)]
fn main() {
client.sign_out().await?;
}

This revokes the auth key on Telegram’s servers and deletes the local session file.

How the DH auth key exchange works

Under the hood, every new session establishes a shared auth key via a 3-step Diffie-Hellman exchange before any login code is ever sent. This key is what secures the entire session.

1. Client sends req_pq_multi: server responds with a pq product
2. Client factorises pq into primes (Pollard’s rho), encrypts its DH parameters with the server’s RSA key
3. Server responds with server_DH_params_ok: client completes g^ab mod p
4. Both sides now share a 2048-bit auth key: login code is sent encrypted using this key

See Crate Architecture for more on the MTProto internals.

Bot Login

Bot login is simpler than user login: just a single call with a bot token.

Just want something working? Client::quick_connect prompts for a bot token interactively and handles the full flow in one call. This page covers the explicit bot_sign_in path for when you need non-interactive auth or more control.

Getting a bot token

1. Open Telegram and start a chat with @BotFather
2. Send /newbot
3. Follow the prompts to choose a name and username
4. BotFather gives you a token like: 1234567890:ABCdefGHIjklMNOpqrSTUvwxYZ

Login

#![allow(unused)]
fn main() {
client.bot_sign_in("1234567890:ABCdef...").await?;
client.save_session().await?;
}

That’s it. On the next run, is_authorized() returns true and you skip the login entirely:

#![allow(unused)]
fn main() {
if !client.is_authorized().await? {
    client.bot_sign_in(BOT_TOKEN).await?;
    client.save_session().await?;
}
}

Get bot info

After login you can fetch the bot’s own User object:

#![allow(unused)]
fn main() {
let me = client.get_me().await?;
println!("Bot: @{}", me.username.as_deref().unwrap_or("?"));
println!("ID: {}", me.id);
println!("Is bot: {}", me.bot);
}

Environment variables (recommended)

Don’t hardcode credentials in source code. Use environment variables instead:

#![allow(unused)]
fn main() {
let api_id: i32   = std::env::var("API_ID")?.parse()?;
let api_hash      = std::env::var("API_HASH")?;
let bot_token     = std::env::var("BOT_TOKEN")?;
}

Then run:

API_ID=12345 API_HASH=abc123 BOT_TOKEN=xxx:yyy cargo run

Or put them in a .env file and use the dotenvy crate.

Two-Factor Authentication (2FA)

Telegram’s 2FA uses Secure Remote Password (SRP): a zero-knowledge proof. Your password is never sent to Telegram’s servers; only a cryptographic proof is transmitted.

How it works in ferogram

#![allow(unused)]
fn main() {
match client.sign_in(&login_token, &code).await {
    Ok(name) => {
        // ✅ No 2FA: login complete
        println!("Welcome, {name}!");
    }
    Err(SignInError::PasswordRequired(password_token)) => {
        // 2FA is enabled: the password_token carries SRP parameters
        client.check_password(password_token, "my_2fa_password").await?;
        println!("✅ 2FA verified");
    }
    Err(e) => return Err(e.into()),
}
}

check_password performs the full SRP computation internally:

1. Downloads SRP parameters from Telegram (account.getPassword)
2. Derives a verifier from your password using PBKDF2-SHA512
3. Computes the SRP proof and sends it (auth.checkPassword)

Getting the password hint

The PasswordToken gives you access to the hint the user set when enabling 2FA:

#![allow(unused)]
fn main() {
Err(SignInError::PasswordRequired(token)) => {
    let hint = token.hint().unwrap_or("no hint set");
    println!("Enter your 2FA password (hint: {hint}):");
    let pw = read_line();
    client.check_password(token, &pw).await?;
}
}

Changing the 2FA password

NOTE: Changing 2FA password requires calling account.updatePasswordSettings via raw API. This is an advanced operation: see Raw API Access.

Wrong password errors

#![allow(unused)]
fn main() {
use ferogram::{InvocationError, RpcError};

match client.check_password(token, &pw).await {
    Ok(_) => println!("✅ OK"),
    Err(InvocationError::Rpc(RpcError { message, .. }))
        if message.contains("PASSWORD_HASH_INVALID") =>
    {
        println!("❌ Wrong password. Try again.");
    }
    Err(e) => return Err(e.into()),
}
}

Security notes

• ferogram-crypto implements the SRP math from scratch: no external SRP library
• The password derivation uses PBKDF2-SHA512 with 100,000+ iterations
• The SRP exchange is authenticated: a MITM cannot substitute their own verifier

Session Persistence

A session stores your auth key, DC address, and peer access-hash cache. Without it, you’d need to log in on every run.

Binary file (default)

#![allow(unused)]
fn main() {
use ferogram::{Client, Config};

let (client, _shutdown) = Client::builder()
        .api_id(12345)
        .api_hash("abc123")
        .session("my.session")
        .connect().await?.await?;
}

After login, save to disk:

#![allow(unused)]
fn main() {
client.save_session().await?;
}

The file is created at session_path and reloaded automatically on the next Client::connect. Keep it in .gitignore: it grants full API access to your account.

In-memory (ephemeral)

Nothing written to disk. Useful for tests or short-lived scripts:

#![allow(unused)]
fn main() {
use ferogram::session_backend::InMemoryBackend;

let (client, _shutdown) = Client::builder()
    .session(InMemoryBackend::new())
    .api_id(12345)
    .api_hash("abc123")
    .connect()
    .await?;
}

Login is required on every run since nothing persists.

SQLite (local database)

ferogram = { version = "0.3.6", features = ["sqlite-session"] }

#![allow(unused)]
fn main() {
let (client, _shutdown) = Client::connect(Config {
    ..Default::default()
}).await?;
}

SQLite is more resilient against crash-corruption than the binary format. Ideal for production bots.

String session: New in v0.2.0

Encode the entire session as a portable base64 string. Store it in an env var, a DB column, or CI secrets:

#![allow(unused)]
fn main() {
// Export (after login)
let s = client.export_session_string().await?;
// → "AQAAAAEDAADtE1lMHBT7...=="

// Restore
let (client, _shutdown) = Client::with_string_session(
    &s, api_id, api_hash,
).await?;

// Or via builder
use ferogram::session_backend::StringSessionBackend;
let (client, _shutdown) = Client::builder()
    .session(StringSessionBackend::new(&s))
    .api_id(api_id)
    .api_hash(api_hash)
    .connect()
    .await?;
}

See Session Backends for the full guide including LibSQL (Turso) backend.

What’s stored in a session

Security

SECURITY: A stolen session file gives full API access to your account. Protect it like a password.

• Add to .gitignore: *.session, *.session.db
• Set restrictive permissions: chmod 600 my.session
• Never log or print session file contents
• If compromised: revoke from Telegram → Settings → Devices → Terminate session

Multi-session / multi-account

Each Client::connect loads one session. For multiple accounts, use multiple files:

#![allow(unused)]
fn main() {
let (client_a, _) = Client::connect(Config {
    api_id, api_hash: api_hash.clone(), ..Default::default()
}).await?;

let (client_b, _) = Client::connect(Config {
    api_id, api_hash: api_hash.clone(), ..Default::default()
}).await?;
}

Session Backends

ferogram ships five session backends out of the box. They all implement the SessionBackend trait and are hot-swappable: switch by changing one line.

Built-in backends

BinaryFileBackend (default)

Saves the session as a binary file on disk. No feature flag needed.

#![allow(unused)]
fn main() {
use ferogram::Client;

let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session("my.session")  // BinaryFileBackend at this path
    .connect()
    .await?;
}

Or construct directly:

#![allow(unused)]
fn main() {
use ferogram::session_backend::BinaryFileBackend;
use std::sync::Arc;

let backend = Arc::new(BinaryFileBackend::new("bot.session"));
}

InMemoryBackend

Non-persistent: lost on process exit. Ideal for tests.

#![allow(unused)]
fn main() {
let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .in_memory()
    .connect()
    .await?;
}

Or construct directly:

#![allow(unused)]
fn main() {
use ferogram::session_backend::InMemoryBackend;
use std::sync::Arc;

let backend = Arc::new(InMemoryBackend::new());
}

StringSessionBackend: portable auth

Encodes the entire session (auth key + DC + peer cache) as a single base64 string. Store it in an environment variable, a database column, or a secret manager.

Export

#![allow(unused)]
fn main() {
let session_string = client.export_session_string().await?;
println!("{session_string}"); // store this somewhere safe
}

Restore

#![allow(unused)]
fn main() {
// Via builder
let session = std::env::var("TG_SESSION").unwrap_or_default();

let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session_string(session)
    .connect()
    .await?;
}

#![allow(unused)]
fn main() {
// Via Config shorthand
let (client, _shutdown) = Client::connect(Config::with_string_session(session_string))
    .await?;
}

#![allow(unused)]
fn main() {
// Construct backend directly
use ferogram::session_backend::StringSessionBackend;
use std::sync::Arc;

let backend = Arc::new(StringSessionBackend::new(session_string));
}

Pass an empty string to start a fresh session with no stored data.

SqliteBackend: local database

Requires feature flag:

ferogram = { version = "0.3.6", features = ["sqlite-session"] }

#![allow(unused)]
fn main() {
use ferogram::SqliteBackend;
use std::sync::Arc;

let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session_backend(Arc::new(SqliteBackend::new("sessions.db")))
    .connect()
    .await?;
}

The file is created if it doesn’t exist.

LibSqlBackend: libsql / Turso

Requires feature flag:

ferogram = { version = "0.3.6", features = ["libsql-session"] }

#![allow(unused)]
fn main() {
use ferogram::LibSqlBackend;
use std::sync::Arc;

// Local embedded database
let backend = LibSqlBackend::new("local.db");

// Remote Turso database
let backend = LibSqlBackend::remote(
    "libsql://your-db.turso.io",
    "your-turso-auth-token",
);

let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session_backend(Arc::new(backend))
    .connect()
    .await?;
}

Custom backend

Implement SessionBackend to use any storage: Redis, Postgres, S3, or anything else:

#![allow(unused)]
fn main() {
use ferogram::session_backend::{SessionBackend, PersistedSession, DcEntry, UpdateStateChange};
use std::io;

struct MyBackend {
    // your fields (e.g. a DB pool)
}

impl SessionBackend for MyBackend {
    fn save(&self, session: &PersistedSession) -> io::Result<()> {
        // Serialize and store session
        let bytes = serde_json::to_vec(session)
            .map_err(|e| io::Error::new(io::ErrorKind::Other, e))?;
        // e.g. write to Redis / Postgres
        Ok(())
    }

    fn load(&self) -> io::Result<Option<PersistedSession>> {
        // Load and deserialize
        Ok(None)
    }

    fn delete(&self) -> io::Result<()> {
        Ok(())
    }

    fn name(&self) -> &str {
        "my-custom-backend"
    }

    // Optional: override granular methods for better performance
    // Default impls call load() → mutate → save()

    fn update_dc(&self, entry: &DcEntry) -> io::Result<()> {
        // UPDATE single DC row (e.g. SQL UPDATE)
        todo!()
    }

    fn set_home_dc(&self, dc_id: i32) -> io::Result<()> {
        // UPDATE home_dc column only
        todo!()
    }
}

// Use it
let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session_backend(Arc::new(MyBackend { /* ... */ }))
    .connect()
    .await?;
}

Granular SessionBackend methods

High-performance backends can override these to avoid full load/save round-trips:

Using ClientBuilder to attach a backend

#![allow(unused)]
fn main() {
use std::sync::Arc;
use ferogram::{Client, session_backend::SessionBackend};

async fn connect_with_backend(
    backend: impl SessionBackend + 'static,
    api_id: i32,
    api_hash: &str,
) -> anyhow::Result<()> {
    let (client, _shutdown) = Client::builder()
        .api_id(api_id)
        .api_hash(api_hash)
        .session_backend(Arc::new(backend))
        .connect()
        .await?;

    // ...
    Ok(())
}
}

Additional backend methods

StringSessionBackend::current()

Reads the current serialised session string at any time:

#![allow(unused)]
fn main() {
use ferogram::session_backend::StringSessionBackend;

let backend = StringSessionBackend::new("");
// ... after connecting and authenticating ...
let s = backend.current(); // base64 session string
}

BinaryFileBackend::path()

#![allow(unused)]
fn main() {
use ferogram::session_backend::BinaryFileBackend;

let backend = BinaryFileBackend::new("bot.session");
println!("Saving to: {}", backend.path().display());
}

InMemoryBackend::snapshot()

Take a point-in-time snapshot of the in-memory session (useful in tests):

#![allow(unused)]
fn main() {
use ferogram::session_backend::InMemoryBackend;

let backend = InMemoryBackend::new();
// ... after auth ...
if let Some(session) = backend.snapshot() {
    // inspect or serialize session data
}
}

Sending Messages

Basic send

#![allow(unused)]
fn main() {
// By username
client.send_message("@username", "Hello!").await?;

// To yourself (Saved Messages)
client.send_message("me", "Note to self").await?;
client.send_to_self("Quick note").await?;

// By numeric ID
client.send_message(123456789_i64, "Hi").await?;
}

send_message accepts anything that implements Into<PeerRef> as the peer (username string, numeric ID, or resolved tl::enums::Peer). The second argument accepts anything that implements Into<InputMessage>, including a bare &str or String for plain text.

Rich messages with InputMessage

InputMessage gives full control over formatting, entities, reply markup, and more:

#![allow(unused)]
fn main() {
use ferogram::InputMessage;

// Plain text
client.send_message("@peer", InputMessage::text("Hello!")).await?;

// Markdown-formatted
client.send_message("@peer", InputMessage::markdown("**Bold** and _italic_ and `code`")).await?;

// HTML-formatted (requires `html` feature)
client.send_message("@peer", InputMessage::html("Hello <b>world</b>")).await?;

// Reply to a message
let msg = InputMessage::text("This is a reply").reply_to(Some(original_id));
client.send_message("@peer", msg).await?;

// Silent message (no notification)
let msg = InputMessage::text("Quiet update").silent(true);
client.send_message("@peer", msg).await?;
}

Message shorthands on IncomingMessage

Every received message exposes shorthand methods that embed the client:

#![allow(unused)]
fn main() {
// Quote-reply in the same chat
msg.reply(InputMessage::text("Got it!")).await?;

// Send to the same chat without quoting
msg.respond("Noted.").await?;

// Edit the message
msg.edit(InputMessage::text("Updated!")).await?;

// Forward to another chat
msg.forward_to("@other_chat").await?;

// Delete
msg.delete().await?;

// Pin / unpin
msg.pin().await?;
msg.unpin().await?;

// Mark as read
msg.mark_read().await?;

// Reload from server
msg.refetch().await?;

// Fetch the message being replied to
if let Some(parent) = msg.get_reply().await? {
    println!("Replied to: {}", parent.text().unwrap_or(""));
}
}

All of these have explicit _with(client, ...) variants for use outside handler closures.

Inline keyboards with InputMessage

#![allow(unused)]
fn main() {
use ferogram::{InputMessage, InlineKeyboard, Button};

let kb = InlineKeyboard::new()
    .row([
        Button::callback("✅ Yes", b"yes"),
        Button::callback("❌ No",  b"no"),
    ]);

let msg = InputMessage::text("Confirm?").reply_markup(kb);
client.send_message("@peer", msg).await?;
}

Clicking inline buttons

Three targeting modes via ButtonFilter:

#![allow(unused)]
fn main() {
use ferogram::update::ButtonFilter;

// By position (row, col - 0-based)
msg.click_button(ButtonFilter::Pos(0, 0)).await?;

// By exact button label
msg.click_button(ButtonFilter::Text("✅ Yes")).await?;

// By callback data bytes
msg.click_button(ButtonFilter::Data(b"action:buy")).await?;

// By arbitrary predicate
msg.click_button_where(|text, data| text.starts_with("✅")).await?;
}

find_button and find_button_where return Option<(row, col)> without sending anything.

Edit, forward, delete, pin (standalone client methods)

#![allow(unused)]
fn main() {
// Edit by message ID
client.edit_message("@peer", msg_id, InputMessage::text("New text")).await?;

// Forward messages
client.forward_messages("@source", &[id1, id2], "@dest").await?;

// Delete messages (revoke = remove for everyone)
client.delete_messages(&[msg_id_1, msg_id_2], true).await?;

// Pin / unpin
client.pin_message("@peer", msg_id).await?;
client.pin_message("@peer", msg_id, false).await?;
client.unpin_all_messages("@peer").await?;

// Get pinned message
let pinned = client.get_pinned_message("@peer").await?;

// Mark as read
client.mark_read("@peer").await?;

// Export a permanent message link
let link = client.export_message_link("@peer", msg_id).await?;

// Who has read a message (groups/channels with read receipts)
let readers = client.get_message_read_participants("@peer", msg_id).await?;
}

Fetch message history

#![allow(unused)]
fn main() {
// get_message_history(peer, limit, offset_id)
// offset_id = 0 starts from the newest
let messages = client.get_message_history("@peer", 50, 0).await?;

for msg in messages {
    println!("{}: {}", msg.id(), msg.text().unwrap_or(""));
}

// Lazy iterator (auto-paginating)
let mut iter = client.iter_messages("@peer");
while let Some(msg) = iter.next(&client).await {
    println!("{}", msg.text().unwrap_or(""));
}
}

Scheduled messages

#![allow(unused)]
fn main() {
use ferogram::InputMessage;

// Schedule at a Unix timestamp
let msg = InputMessage::text("Happy New Year!").schedule_date(Some(1735689600));
client.send_message("@peer", msg).await?;

// Schedule to send when the recipient comes online
let msg = InputMessage::text("Hey!").schedule_once_online();
client.send_message("@peer", msg).await?;

// List scheduled messages
let scheduled = client.get_scheduled_messages("@peer").await?;

// Send a scheduled message immediately
client.send_scheduled_now("@peer", &[scheduled_id]).await?;

// Cancel a scheduled message
client.delete_scheduled_messages("@peer", &[scheduled_id]).await?;
}

Drafts

#![allow(unused)]
fn main() {
// Save or update a draft
client.save_draft("@peer", "Draft text").await?;

// Trigger server push of all drafts as update events
client.sync_drafts().await?;

// Delete all drafts
client.clear_all_drafts().await?;
}

Receiving Updates

The update stream

stream_updates() returns an async stream of typed Update events:

#![allow(unused)]
fn main() {
use ferogram::update::Update;

let mut updates = client.stream_updates();

while let Some(update) = updates.next().await {
    match update {
        Update::NewMessage(msg)     => { /* new message arrived */ }
        Update::MessageEdited(msg)  => { /* message was edited */ }
        Update::MessageDeleted(del) => { /* message was deleted */ }
        Update::CallbackQuery(cb)   => { /* inline button pressed */ }
        Update::InlineQuery(iq)     => { /* @bot query in another chat */ }
        Update::InlineSend(is)      => { /* inline result was chosen */ }
        Update::Raw(raw)            => { /* any other update by constructor ID */ }
        _ => {}
    }
}
}

Concurrent update handling

For bots under load, spawn each update into its own task so the receive loop never blocks:

#![allow(unused)]
fn main() {
use std::sync::Arc;

let client = Arc::new(client);
let mut updates = client.stream_updates();

while let Some(update) = updates.next().await {
    let client = client.clone();
    tokio::spawn(async move {
        handle(update, client).await;
    });
}
}

Filtering outgoing messages

In user accounts, your own sent messages come back as updates with out = true. Filter them:

#![allow(unused)]
fn main() {
Update::NewMessage(msg) if !msg.outgoing() => {
    // only incoming messages
}
}

MessageDeleted

Deleted message updates only contain the message IDs, not the content:

#![allow(unused)]
fn main() {
Update::MessageDeleted(del) => {
    println!("Deleted IDs: {:?}", del.messages());
    // del.channel_id(): Some if deleted from a channel
}
}

Inline Keyboards & Reply Markup

ferogram ships with two high-level keyboard builders: InlineKeyboard and ReplyKeyboard: so you never have to construct raw TL types by hand.

Both builders are in ferogram::keyboard and re-exported at the crate root:

#![allow(unused)]
fn main() {
use ferogram::keyboard::{Button, InlineKeyboard, ReplyKeyboard};
}

InlineKeyboard: buttons attached to a message

Inline keyboards appear below a message and trigger Update::CallbackQuery when tapped.

#![allow(unused)]
fn main() {
use ferogram::keyboard::{Button, InlineKeyboard};
use ferogram::InputMessage;

let kb = InlineKeyboard::new()
    .row([
        Button::callback("✅ Yes", b"confirm:yes"),
        Button::callback("❌ No",  b"confirm:no"),
    ])
    .row([
        Button::url("📖 Docs", "https://docs.rs/ferogram"),
    ]);

client.send_message(peer.clone(), InputMessage::text("Do you want to proceed?").keyboard(kb)).await?;
}

InlineKeyboard methods

InlineKeyboard implements Into<tl::enums::ReplyMarkup>, so you can also pass it directly to InputMessage::reply_markup().

Button: all button types

Callback, URL, and common types

#![allow(unused)]
fn main() {
// Sends data to your bot as Update::CallbackQuery (max 64 bytes)
Button::callback("✅ Confirm", b"action:confirm")

// Opens URL in a browser
Button::url("🌐 Website", "https://example.com")

// Copy text to clipboard (Telegram 10.3+)
Button::copy_text("📋 Copy code", "PROMO2024")

// Login-widget: authenticates user before opening URL
Button::url_auth("🔐 Login", "https://example.com/auth", None, bot_input_user)

// Opens bot inline mode in the current chat with query pre-filled
Button::switch_inline("🔍 Search here", "default query")

// Chat picker so user can choose which chat to use inline mode in
Button::switch_elsewhere("📤 Share", "")

// Telegram Mini App with full JS bridge
Button::webview("🚀 Open App", "https://myapp.example.com")

// Simple webview without JS bridge
Button::simple_webview("ℹ️ Info", "https://info.example.com")

// Plain text for reply keyboards
Button::text("📸 Send photo")

// Launch a Telegram game (bots only)
Button::game("🎮 Play")

// Payment buy button (bots only, used with invoice)
Button::buy("💳 Pay $4.99")
}

Reply-keyboard-only buttons

#![allow(unused)]
fn main() {
// Shares user's phone number on tap
Button::request_phone("📞 Share my number")

// Shares user's location on tap
Button::request_geo("📍 Share location")

// Opens poll creation interface
Button::request_poll("📊 Create poll")

// Forces quiz mode in poll creator
Button::request_quiz("🧠 Create quiz")
}

Escape hatch

#![allow(unused)]
fn main() {
// Get the underlying tl::enums::KeyboardButton
let raw = Button::callback("x", b"x").into_raw();
}

ReplyKeyboard: replacement keyboard

A reply keyboard replaces the user’s text input keyboard until dismissed. The user’s tap arrives as a plain-text Update::NewMessage.

#![allow(unused)]
fn main() {
use ferogram::keyboard::{Button, ReplyKeyboard};

let kb = ReplyKeyboard::new()
    .row([
        Button::text("📸 Photo"),
        Button::text("📄 Document"),
    ])
    .row([Button::text("❌ Cancel")])
    .resize()      // shrink to fit content (recommended)
    .single_use(); // hide after one press

client.send_message(peer.clone(), InputMessage::text("Choose file type:").keyboard(kb))
    .await?;
}

ReplyKeyboard methods

Remove keyboard

#![allow(unused)]
fn main() {
use ferogram_tl_types as tl;

let remove = tl::enums::ReplyMarkup::ReplyKeyboardHide(
    tl::types::ReplyKeyboardHide { selective: false }
);
client
    .send_message(peer.clone(), InputMessage::text("Done.").reply_markup(remove))
    .await?;
}

Answer callback queries

Always answer every CallbackQuery: Telegram shows a loading spinner until you do.

#![allow(unused)]
fn main() {
Update::CallbackQuery(cb) => {
    let data = cb.data().unwrap_or(b"");
    match data {
        b"confirm:yes" => client.answer_callback_query(cb.query_id, Some("✅ Done!"), false).await?,
        b"confirm:no"  => client.answer_callback_query(cb.query_id, Some("❌ Cancelled"), false).await?,
        _              => client.answer_callback_query(cb.query_id, None, false).await?,
    }
}
}

Pass alert: true to show a popup alert instead of a toast:

#![allow(unused)]
fn main() {
client.answer_callback_query(cb.query_id, Some("⛔ Access denied"), true).await?;
}

Legacy raw TL pattern (still works)

If you prefer constructing TL types directly:

#![allow(unused)]
fn main() {
fn inline_kb(rows: Vec<Vec<tl::enums::KeyboardButton>>) -> tl::enums::ReplyMarkup {

```rust
use ferogram_tl_types as tl;

fn inline_kb(rows: Vec<Vec<tl::enums::KeyboardButton>>) -> tl::enums::ReplyMarkup {
    tl::enums::ReplyMarkup::ReplyInlineMarkup(tl::types::ReplyInlineMarkup {
        rows: rows.into_iter().map(|buttons|
            tl::enums::KeyboardButtonRow::KeyboardButtonRow(
                tl::types::KeyboardButtonRow { buttons }
            )
        ).collect(),
    })
}

fn btn_cb(text: &str, data: &str) -> tl::enums::KeyboardButton {
    tl::enums::KeyboardButton::Callback(tl::types::KeyboardButtonCallback {
        requires_password: false,
        style:             None,
        text:              text.into(),
        data:              data.as_bytes().to_vec(),
    })
}

fn btn_url(text: &str, url: &str) -> tl::enums::KeyboardButton {
    tl::enums::KeyboardButton::Url(tl::types::KeyboardButtonUrl {
        style: None,
        text:  text.into(),
        url:   url.into(),
    })
}
}

Send with keyboard

#![allow(unused)]
fn main() {
let kb = inline_kb(vec![
    vec![btn_cb("✅ Yes", "confirm:yes"), btn_cb("❌ No", "confirm:no")],
    vec![btn_url("🌐 Docs", "https://github.com/ankit-chaubey/ferogram")],
]);

let (text, entities) = parse_markdown("**Do you want to proceed?**");
let msg = InputMessage::text(text)
    .entities(entities)
    .reply_markup(kb);

client.send_message(peer, msg).await?;
}

All button types

Switch Inline button

Opens the bot’s inline mode in the current or another chat:

#![allow(unused)]
fn main() {
tl::enums::KeyboardButton::SwitchInline(tl::types::KeyboardButtonSwitchInline {
    same_peer:  false, // false = let user pick any chat
    text:       "🔍 Search with me".into(),
    query:      "default query".into(),
    peer_types: None,
})
}

Web App button

#![allow(unused)]
fn main() {
tl::enums::KeyboardButton::SimpleWebView(tl::types::KeyboardButtonSimpleWebView {
    text: "Open App".into(),
    url:  "https://myapp.example.com".into(),
})
}

Reply keyboard (replaces user’s keyboard)

#![allow(unused)]
fn main() {
let reply_kb = tl::enums::ReplyMarkup::ReplyKeyboardMarkup(
    tl::types::ReplyKeyboardMarkup {
        resize:      true,       // shrink to fit buttons
        single_use:  true,       // hide after one tap
        selective:   false,      // show to everyone
        persistent:  false,      // don't keep after message
        placeholder: Some("Choose an option…".into()),
        rows: vec![
            tl::enums::KeyboardButtonRow::KeyboardButtonRow(
                tl::types::KeyboardButtonRow {
                    buttons: vec![
                        tl::enums::KeyboardButton::KeyboardButton(
                            tl::types::KeyboardButton { text: "🍕 Pizza".into() }
                        ),
                        tl::enums::KeyboardButton::KeyboardButton(
                            tl::types::KeyboardButton { text: "🍔 Burger".into() }
                        ),
                    ]
                }
            ),
            tl::enums::KeyboardButtonRow::KeyboardButtonRow(
                tl::types::KeyboardButtonRow {
                    buttons: vec![
                        tl::enums::KeyboardButton::KeyboardButton(
                            tl::types::KeyboardButton { text: "❌ Cancel".into() }
                        ),
                    ]
                }
            ),
        ],
    }
);
}

The user’s choices arrive as plain text NewMessage updates.

Remove keyboard

#![allow(unused)]
fn main() {
let remove = tl::enums::ReplyMarkup::ReplyKeyboardHide(
    tl::types::ReplyKeyboardHide { selective: false }
);
let msg = InputMessage::text("Keyboard removed.").reply_markup(remove);
}

Button data format

Telegram limits callback button data to 64 bytes. Use compact, parseable formats:

#![allow(unused)]
fn main() {
// Good: structured, compact
"vote:yes"
"page:3"
"item:42:delete"
"menu:settings:notifications"

// Bad: verbose
"user_clicked_the_settings_button"
}

Media & Files

Upload

ferogram provides three upload methods. Choose based on file size and where the data comes from.

#![allow(unused)]
fn main() {
let uploaded = client.upload_file("/tmp/photo.jpg").await?;
client.send_media(peer, InputMessage::media(uploaded.as_photo_media())).await?;
}

#![allow(unused)]
fn main() {
// from a Vec<u8>
use std::io::Cursor;
let uploaded = client.upload(Cursor::new(bytes), "photo.jpg").await?;

// from a tokio File
let f = tokio::fs::File::open("video.mp4").await?;
let uploaded = client.upload(f, "video.mp4").await?;
}

#![allow(unused)]
fn main() {
let bytes: Vec<u8> = std::fs::read("photo.jpg")?;
let uploaded = client.upload_file("/tmp/photo.jpg").await?;
}

UploadedFile methods

Upload media (reusable)

Upload a file to Telegram’s servers and get back an InputMedia handle that can be reused in multiple sends without re-uploading:

#![allow(unused)]
fn main() {
use ferogram::InputMessage;

let uploaded = client.upload_file(&bytes, "photo.jpg", "image/jpeg").await?;
let media = uploaded.as_photo_media();

// Upload to Telegram's servers (no message sent)
let stored = client.upload_media("@peer", media.clone()).await?;

// Reuse the stored media handle
let msg = InputMessage::text("Here it is!").copy_media(stored.into_input_media());
client.send_message("@peer", msg).await?;
}

Send file

#![allow(unused)]
fn main() {
use ferogram::InputMessage;

// Send a file as document or photo
let uploaded = client.upload_file(&bytes, "photo.jpg", "image/jpeg").await?;
client.send_file("@peer", uploaded.as_photo_media(), &InputMessage::text("Caption")).await?;

// Or attach via InputMessage
let msg = InputMessage::text("Here is the file")
    .copy_media(uploaded.as_document_media());
client.send_message("@peer", msg).await?;

// Send as album (multiple files in one message group)
client.send_album("@peer", vec![
    uploaded_a.as_photo_media(),
    uploaded_b.as_photo_media(),
]).await?;
}

AlbumItem: per-item control in albums

#![allow(unused)]
fn main() {
use ferogram::media::AlbumItem;

let items = vec![
    AlbumItem::new(uploaded_a.as_photo_media())
        .caption("First photo 📸"),
    AlbumItem::new(uploaded_b.as_document_media())
        .caption("The report 📄")
        .reply_to(Some(msg_id)),
];
client.send_album(peer.clone(), items).await?;
}

Download

#![allow(unused)]
fn main() {
// To bytes: sequential
```rust
let mut buf = Vec::new();
client.download(msg.media().unwrap(), &mut buf).await?;

client.download_file(msg.media().unwrap(), "/tmp/output.jpg").await?;

let bytes = msg.bytes().await?;                        // → Vec<u8>

let mut file = tokio::fs::File::create("out.mp4").await?;
msg.download(&mut file).await?;                        // stream to file

if let Some(mut iter) = client.iter_download(msg.media().unwrap()) {
    while let Some(chunk) = iter.next().await? {
        // chunk: bytes::Bytes - zero-copy slice
        process(&chunk);
    }
}
}

Downloadable trait

Downloadable trait

Photo, Document, and Sticker all implement Downloadable, so you can use client.download_item(&item) (internal) on any of them uniformly. For the public API, pass msg.media() to client.download.

#![allow(unused)]
fn main() {
use ferogram::media::Downloadable;

async fn save_any<D: Downloadable>(client: &Client, item: &D) -> Vec<u8> {
    // internal method - public API uses client.download(media, dest)
    client.download(item).await.unwrap()
}
}

Download location from message

#![allow(unused)]
fn main() {
// Get an InputFileLocation from the raw message
use ferogram::media::download_location_from_media;

// use msg.bytes() or client.download(msg.media().unwrap(), &mut buf) instead

// Or via IncomingMessage convenience:
client.download_file(msg.media().unwrap(), "output.jpg").await?;
}

Media groups (albums)

When Telegram delivers a grouped media send (album), each message in the group carries the same grouped_id. To fetch all messages belonging to the same album as a known message ID:

#![allow(unused)]
fn main() {
let msgs = client.get_media_group("@mychannel", 42).await?;
println!("{} messages in this album", msgs.len());

for m in &msgs {
    if let Some(photo) = m.photo() {
        println!("  photo id={}", photo.id());
    } else if let Some(doc) = m.document() {
        println!("  document mime={}", doc.mime_type().unwrap_or("?"));
    }
}
}

get_media_group accepts any peer and a message ID that is part of the album. It returns all messages in the group including the seed message. For non-channel chats the server returns only the single message.

Detecting albums in the update stream

#![allow(unused)]
fn main() {
if let Update::NewMessage(msg) = update {
    if msg.grouped_id().is_some() {
        // This message is part of an album; you can call
        // client.get_media_group(msg.peer_id(), msg.id()).await
        // to retrieve the full set.
    }
}
}

Message Formatting

Telegram supports rich text formatting through message entities: positional markers that indicate bold, italic, code, links, and more.

Quickest way: InputMessage constructors

The simplest approach is InputMessage::markdown or InputMessage::html, which parse the text and attach entities in one call:

#![allow(unused)]
fn main() {
use ferogram::InputMessage;

// Markdown
let msg = InputMessage::markdown("**Bold**, _italic_, `code`");

// HTML
let msg = InputMessage::html("<b>Bold</b>, <i>italic</i>, <code>code</code>");

client.send_message(peer, msg).await?;
}

If you just want to send without building an InputMessage first, the convenience methods do the same thing in one step:

#![allow(unused)]
fn main() {
client.send_message(peer, InputMessage::html("<b>Bold</b> and <i>italic</i>")).await?;
client.send_message(peer, InputMessage::markdown("**Bold** and _italic_")).await?;
}

Using parse_markdown directly

If you need the (String, Vec<MessageEntity>) tuple for further processing:

#![allow(unused)]
fn main() {
use ferogram::parsers::parse_markdown;
use ferogram::InputMessage;

let (plain, entities) = parse_markdown("**Bold text**, _italic_, `inline code`");

let msg = InputMessage::text(plain).entities(entities);
client.send_message(peer, msg).await?;
}

Markdown syntax

parse_markdown follows the Telegram Bot API MarkdownV2 spec. __text__ is Underline, not Italic. For the legacy V1 behaviour call parse_markdown_v1 (deprecated, removed in 0.4.0).

HTML syntax

Supported tags:

Building entities manually

For full control, construct MessageEntity values directly:

#![allow(unused)]
fn main() {
use ferogram_tl_types as tl;

let text = "Hello world";
let entities = vec![
    tl::enums::MessageEntity::Bold(tl::types::MessageEntityBold {
        offset: 0,
        length: 5,
    }),
    tl::enums::MessageEntity::Code(tl::types::MessageEntityCode {
        offset: 6,
        length: 5,
    }),
];

let msg = InputMessage::text(text).entities(entities);
}

Pre block with language

#![allow(unused)]
fn main() {
tl::enums::MessageEntity::Pre(tl::types::MessageEntityPre {
    offset:   0,
    length:   code_text.encode_utf16().count() as i32,
    language: "rust".into(),
})
}

Mention by user ID

#![allow(unused)]
fn main() {
tl::enums::MessageEntity::MentionName(tl::types::MessageEntityMentionName {
    offset:  0,
    length:  label.encode_utf16().count() as i32,
    user_id: 123456789,
})
}

Blockquote

messageEntityBlockquote has an optional collapsed flag:

#![allow(unused)]
fn main() {
tl::enums::MessageEntity::Blockquote(tl::types::MessageEntityBlockquote {
    collapsed: false, // true = collapsible quote
    offset: 0,
    length: text.encode_utf16().count() as i32,
})
}

FormattedDate

Displays a Unix timestamp in the user’s local timezone and locale. Set the boolean flags you want; the rest default to false:

#![allow(unused)]
fn main() {
tl::enums::MessageEntity::FormattedDate(tl::types::MessageEntityFormattedDate {
    relative:    false,
    short_time:  false,
    long_time:   false,
    short_date:  true,  // e.g. "Jan 5"
    long_date:   false,
    day_of_week: false,
    offset: 0,
    length: placeholder_text.encode_utf16().count() as i32,
    date:   1736000000, // Unix timestamp
})
}

Generating markup from entities

Both generate_markdown and generate_html are available if you need to serialise entities back to text:

#![allow(unused)]
fn main() {
use ferogram::parsers::{generate_markdown, generate_html};

let md  = generate_markdown(plain_text, &entities);
let htm = generate_html(plain_text, &entities);
}

generate_markdown emits full MarkdownV2 syntax including __text__ for Underline, ~text~ for Strike, and > prefix for Blockquote.

All entity types

Reactions

Reactions are emoji responses attached to messages. They appear below messages with per-emoji counts.

ferogram provides the InputReactions builder. It converts from &str and String automatically, so simple cases need no import.

Send a reaction

#![allow(unused)]
fn main() {
use ferogram::reactions::InputReactions;

// Standard emoji: shorthand (no import needed, &str converts automatically)
client.send_reaction(peer.clone(), message_id, "👍").await?;

// Standard emoji: explicit builder
client.send_reaction(peer.clone(), message_id, InputReactions::emoticon("🔥")).await?;

// Custom (premium) emoji by document_id
client.send_reaction(peer.clone(), message_id, InputReactions::custom_emoji(1234567890)).await?;

// Remove all reactions from the message
client.send_reaction(peer.clone(), message_id, InputReactions::remove()).await?;
}

Modifiers

Chain modifiers after a constructor:

#![allow(unused)]
fn main() {
// Big animated reaction (full-screen effect)
client.send_reaction(peer.clone(), message_id,
    InputReactions::emoticon("🔥").big()
).await?;

// Add to the user's recently-used reaction list
client.send_reaction(peer.clone(), message_id,
    InputReactions::emoticon("❤️").add_to_recent()
).await?;

// Both at once
client.send_reaction(peer.clone(), message_id,
    InputReactions::emoticon("🎉").big().add_to_recent()
).await?;
}

Multi-reaction (premium users)

#![allow(unused)]
fn main() {
use ferogram_tl_types::{enums::Reaction, types};

client.send_reaction(
    peer.clone(),
    message_id,
    InputReactions::from(vec![
        Reaction::Emoji(types::ReactionEmoji { emoticon: "👍".into() }),
        Reaction::Emoji(types::ReactionEmoji { emoticon: "❤️".into() }),
    ]),
).await?;
}

InputReactions API reference

InputReactions also implements From<&str> and From<String>, so you can pass a plain emoji string directly to send_reaction.

Reading reactions from a message

Reactions are embedded in msg.raw:

#![allow(unused)]
fn main() {
Update::NewMessage(msg) => {
    if let tl::enums::Message::Message(m) = &msg.raw {
        if let Some(tl::enums::MessageReactions::MessageReactions(r)) = &m.reactions {
            for result in &r.results {
                if let tl::enums::ReactionCount::ReactionCount(rc) = result {
                    match &rc.reaction {
                        tl::enums::Reaction::Emoji(e) => {
                            println!("{}: {} users", e.emoticon, rc.count);
                        }
                        tl::enums::Reaction::CustomEmoji(e) => {
                            println!("custom {}: {} users", e.document_id, rc.count);
                        }
                        _ => {}
                    }
                }
            }
        }
    }
}
}

Raw API: who reacted

To see which users chose a specific reaction:

#![allow(unused)]
fn main() {
use ferogram_tl_types::{functions, enums, types};

let result = client.invoke(&functions::messages::GetMessageReactionsList {
    peer:     peer_input,
    id:       message_id,
    reaction: Some(enums::Reaction::Emoji(types::ReactionEmoji {
        emoticon: "👍".into(),
    })),
    offset:   None,
    limit:    50,
}).await?;

if let enums::messages::MessageReactionsList::MessageReactionsList(list) = result {
    for r in &list.reactions {
        if let enums::MessagePeerReaction::MessagePeerReaction(rr) = r {
            println!("peer: {:?}", rr.peer_id);
        }
    }
}
}

Update Types

stream.next().await yields Option<Update>. Update is #[non_exhaustive]: always include _ => {}.

#![allow(unused)]
fn main() {
use ferogram::update::Update;

while let Some(update) = stream.next().await {
    match update {
        // Messages
        Update::NewMessage(msg)       => { /* IncomingMessage */ }
        Update::MessageEdited(msg)    => { /* IncomingMessage */ }
        Update::MessageDeleted(del)   => { /* MessageDeleted */ }

        // Bot interactions
        Update::CallbackQuery(cb)     => { /* CallbackQuery */ }
        Update::InlineQuery(iq)       => { /* InlineQuery */ }
        Update::InlineSend(is)        => { /* InlineSend */ }

        // Presence
        Update::UserTyping(action)    => { /* UserTyping */ }
        Update::UserStatus(status)    => { /* UserStatus */ }

        // Group/channel events
        Update::ParticipantUpdate(p)  => { /* ParticipantUpdate */ }
        Update::JoinRequest(jr)       => { /* JoinRequest */ }
        Update::MessageReaction(mr)   => { /* MessageReaction */ }
        Update::PollVote(pv)          => { /* PollVote */ }
        Update::BotStopped(bs)        => { /* BotStopped */ }

        // Payments
        Update::ShippingQuery(sq)     => { /* ShippingQuery */ }
        Update::PreCheckoutQuery(pcq) => { /* PreCheckoutQuery */ }

        // Boosts
        Update::ChatBoost(cb)         => { /* ChatBoost */ }

        // Guest chat (bots only)
        Update::GuestChatQuery(q)     => { /* GuestChatQuery */ }

        // Raw passthrough
        Update::Raw(raw)              => { /* RawUpdate */ }

        _ => {}  // required: Update is #[non_exhaustive]
    }
}
}

MessageDeleted

#![allow(unused)]
fn main() {
Update::MessageDeleted(del) => {
    let ids: Vec<i32> = del.into_messages();
}
}

CallbackQuery

See the full Callback Queries page.

#![allow(unused)]
fn main() {
cb.query_id      // i64
cb.user_id       // i64
cb.msg_id        // Option<i32>
cb.data()        // Option<&str>
cb.answer()      // → Answer builder
cb.answer_flat(&client, text)
cb.answer_alert(&client, text)
}

InlineQuery

#![allow(unused)]
fn main() {
iq.query_id      // i64
iq.user_id       // i64
iq.query()       // &str: the typed query
iq.offset        // String: pagination offset
}

Answer with client.answer_inline_query(...). See Inline Mode.

InlineSend

Fires when a user picks a result from your bot’s inline mode.

#![allow(unused)]
fn main() {
is.result_id     // String: which result was chosen
is.user_id       // i64
is.query         // String: original query

// Edit the message the inline result was sent as
is.edit_message(&client, updated_input_msg).await?;
}

UserTyping

#![allow(unused)]
fn main() {
Update::UserTyping(action) => {
    action.peer      // tl::enums::Peer: the chat
    action.user_id   // Option<i64>
    action.action    // tl::enums::SendMessageAction
}
}

UserStatus

#![allow(unused)]
fn main() {
Update::UserStatus(status) => {
    status.user_id  // i64
    status.status   // tl::enums::UserStatus
    // variants: UserStatusOnline, UserStatusOffline, UserStatusRecently, etc.
}
}

ParticipantUpdate

Fires when a user joins, leaves, or has their rights changed in a group or channel.

#![allow(unused)]
fn main() {
Update::ParticipantUpdate(p) => {
    p.peer      // tl::enums::Peer: the chat
    p.user_id   // i64
    // p.prev_participant / p.new_participant: Option<tl::enums::ChannelParticipant>
}
}

JoinRequest

Fires when a user submits a join request to a group or channel.

#![allow(unused)]
fn main() {
Update::JoinRequest(jr) => {
    jr.peer     // tl::enums::Peer
    jr.user_id  // i64
    // Approve/decline via client.join_request(peer, user_id, approve)
}
}

MessageReaction

Fires when a reaction is added or removed on a message.

#![allow(unused)]
fn main() {
Update::MessageReaction(mr) => {
    mr.peer    // tl::enums::Peer
    mr.msg_id  // i32
    // mr.reactions: list of current reactions
}
}

PollVote

Fires when a user votes in a poll.

#![allow(unused)]
fn main() {
Update::PollVote(pv) => {
    pv.poll_id  // i64
    pv.user_id  // i64
    // pv.options: Vec<Vec<u8>> - option IDs chosen
}
}

BotStopped

Fires when a user blocks or unblocks the bot.

#![allow(unused)]
fn main() {
Update::BotStopped(bs) => {
    bs.user_id  // i64
    bs.stopped  // bool: true = blocked, false = unblocked
}
}

ShippingQuery

Fires during the payment flow when the user provides a shipping address (for physical goods).

#![allow(unused)]
fn main() {
Update::ShippingQuery(sq) => {
    // sq.query_id, sq.user_id, sq.payload, sq.shipping_address
    client.answer_shipping_query(sq.query_id, true, shipping_options, None).await?;
}
}

PreCheckoutQuery

Fires just before a payment is confirmed.

#![allow(unused)]
fn main() {
Update::PreCheckoutQuery(pcq) => {
    // pcq.query_id, pcq.user_id, pcq.currency, pcq.total_amount, pcq.payload
    client.answer_precheckout_query(pcq.query_id, true, None).await?;
}
}

ChatBoost

Fires when a channel receives a boost event.

#![allow(unused)]
fn main() {
Update::ChatBoost(cb) => {
    cb.peer   // tl::enums::Peer: the channel
    // cb.boost: boost details
}
}

GuestChatQuery

Fires when a user invites the bot into a guest-chat context (updateBotGuestChatQuery). Bots only. GuestChatQuery derefs to IncomingMessage so you can read the message text directly.

#![allow(unused)]
fn main() {
Update::GuestChatQuery(q) => {
    println!("query_id: {}", q.query_id);
    println!("message: {}", q.text());
    println!("qts: {}", q.qts);

    // reference_messages: previous messages for context
    for ref_msg in &q.reference_messages {
        println!("  ref: {}", ref_msg.text());
    }

    // Answer with GuestChatAnswer
    q.answer()
        .article("My result")
        .text("Answer body")
        .send(&client)
        .await?;
}
}

GuestChatAnswer supports all standard inline result kinds: article, photo, document, game, location, venue, contact, webpage, invoice, and raw. Call .send(&client) to submit via messages.setBotGuestChatResult.

RawUpdate

Any TL update that doesn’t map to a typed variant:

#![allow(unused)]
fn main() {
Update::Raw(raw) => {
    raw.update   // tl::enums::Update: the raw TL object
}
}

Raw update stream

If you need all updates unfiltered:

#![allow(unused)]
fn main() {
let mut stream = client.stream_updates();
while let Some(raw) = stream.next_raw().await {
    println!("{:?}", raw.update);
}
}

IncomingMessage

IncomingMessage is the type of Update::NewMessage and Update::MessageEdited. It wraps a raw tl::enums::Message and provides typed accessors plus a full suite of convenience action methods that let you act on a message without passing the Client around explicitly (when the message was received from the update stream it already carries a client reference).

Basic accessors

#![allow(unused)]
fn main() {
Update::NewMessage(msg) => {
    msg.id()                  // i32: unique message ID in this chat
    msg.text()                // Option<&str>: text or media caption
    msg.peer_id()             // Option<&tl::enums::Peer>: chat this is in
    msg.sender_id()           // Option<&tl::enums::Peer>: who sent it
    msg.outgoing()            // bool: sent by us?
    msg.date()                // i32: Unix timestamp
    msg.edit_date()           // Option<i32>: last edit timestamp
    msg.mentioned()           // bool: are we @mentioned?
    msg.silent()              // bool: no notification
    msg.pinned()              // bool: currently pinned
    msg.post()                // bool: channel post (no sender)
    msg.noforwards()          // bool: forwarding disabled
    msg.from_scheduled()      // bool: was a scheduled message
    msg.edit_hide()           // bool: edit not shown in UI
    msg.media_unread()        // bool: media not yet viewed
    msg.raw                   // tl::enums::Message: full TL object
}
}

Extended accessors

#![allow(unused)]
fn main() {
// Counters
msg.forward_count()          // Option<i32>: number of times forwarded
msg.view_count()             // Option<i32>: view count (channels)
msg.reply_count()            // Option<i32>: number of replies in thread
msg.reaction_count()         // i32: total reactions
msg.reply_to_message_id()    // Option<i32>: ID of the message replied to

// Typed timestamps
msg.date_utc()               // Option<DateTime<Utc>>
msg.edit_date_utc()          // Option<DateTime<Utc>>

// Rich content
msg.media()                  // Option<&tl::enums::MessageMedia>
msg.entities()               // Option<&Vec<tl::enums::MessageEntity>>
msg.action()                 // Option<&tl::enums::MessageAction>: service messages
msg.reply_markup()           // Option<&tl::enums::ReplyMarkup>
msg.forward_header()         // Option<&tl::enums::MessageFwdHeader>
msg.grouped_id()             // Option<i64>: album group ID
msg.via_bot_id()             // Option<i64>: inline bot that sent this
msg.post_author()            // Option<&str>: channel post author signature
msg.restriction_reason()     // Option<&Vec<tl::enums::RestrictionReason>>

// Formatted text helpers (requires html feature for html_text)
msg.markdown_text()          // Option<String>: entities rendered as Markdown
msg.html_text()              // Option<String>: entities rendered as HTML

// Typed media extraction
msg.photo()                  // Option<Photo>
msg.document()               // Option<Document>

// Sender details
msg.sender_user_id()         // Option<i64>: sender's user ID
msg.sender_chat_id()         // Option<i64>: sender's chat ID
msg.sender_user()            // async → Option<User> (fetches from cache/API)
}

Convenience action methods

These methods work without passing a &Client when the message came from stream_updates() (the client reference is embedded). Use the _with(client) variants when you hold the message outside an update handler.

Reply

#![allow(unused)]
fn main() {
// Reply to this message (reply_to set automatically)
msg.reply("Got it! ✅").await?;

// Reply with full InputMessage control
msg.reply_ex(
    InputMessage::text("Here you go")
        .silent(true)
        .no_webpage(true)
).await?;

// Explicit client variants
msg.reply_with(&client, "Hi").await?;
msg.reply_ex_with(&client, input_msg).await?;
}

Respond (no reply thread)

#![allow(unused)]
fn main() {
// Send to the same chat without quoting
msg.respond("Hello everyone!").await?;
msg.respond(InputMessage::text("...").keyboard(kb)).await?;

// Explicit client variants
msg.respond_with(&client, "Hi").await?;
msg.respond_with(&client, input_msg).await?;
}

Edit

#![allow(unused)]
fn main() {
// Edit this message's text
msg.edit("Updated content").await?;
msg.edit_with(&client, "Updated content").await?;
}

Delete

#![allow(unused)]
fn main() {
msg.delete().await?;
msg.delete_with(&client).await?;
}

Mark as read

#![allow(unused)]
fn main() {
msg.mark_read().await?;
msg.mark_read_with(&client).await?;
}

Pin / Unpin

#![allow(unused)]
fn main() {
msg.pin().await?;          // pins with notification
msg.pin_with(&client).await?;

msg.unpin().await?;
msg.unpin_with(&client).await?;
}

React

#![allow(unused)]
fn main() {
use ferogram::reactions::InputReactions;

msg.react("👍").await?;
msg.react(InputReactions::emoticon("🔥").big()).await?;
msg.react_with(&client, "❤️").await?;
}

Forward

#![allow(unused)]
fn main() {
// Forward to another peer
msg.forward_to("@someuser").await?;
msg.forward_to_with(&client, peer).await?;
}

Download media

#![allow(unused)]
fn main() {
// Download attached media to a file path, returns true if media existed
// to disk
client.download_file(msg.media().unwrap(), "output.jpg").await?;
// to memory
let bytes = msg.bytes().await?;
}

Fetch replied-to message

#![allow(unused)]
fn main() {
// Get the message this one replies to (attached client required)
if let Some(parent) = msg.get_reply().await? {
    println!("Replying to: {}", parent.text().unwrap_or(""));
}
}

Refetch

#![allow(unused)]
fn main() {
// Re-fetch this message from the server (update its state)
msg.refetch().await?;
msg.refetch_with(&client).await?;
}

Reply-to-message (via Client)

#![allow(unused)]
fn main() {
// Fetch the replied-to message by ID
if let Some(reply_id) = msg.reply_to_message_id() {
    let parent = client.get_messages(msg.peer(), &[reply_id]).await.ok().and_then(|mut v| v.into_iter().next()).await?;
}
}

Full handler example

#![allow(unused)]
fn main() {
use ferogram::{Client, update::Update};

let mut stream = client.stream_updates();
while let Some(update) = stream.next().await {
    match update {
        Update::NewMessage(msg) if !msg.outgoing() => {
            let text = msg.text().unwrap_or("");

            if text == "/start" {
                msg.reply("Welcome! 👋").await.ok();

            } else if text == "/me" {
                if let Ok(Some(user)) = msg.sender_user().await {
                    msg.reply(&format!("You are: {}", user.full_name())).await.ok();
                }

            } else if text.starts_with("/echo ") {
                let echo = &text[6..];
                msg.respond(echo).await.ok();

            } else if let Some(media) = msg.media() {
                msg.reply("Downloading…").await.ok();
                msg.bytes().await.ok();
                msg.react("✅").await.ok();
            }
        }
        _ => {}
    }
}
}

Callback Queries

When a user taps an inline keyboard button, the bot receives Update::CallbackQuery. Always answer it: Telegram shows a loading spinner until you do.

Basic handling

#![allow(unused)]
fn main() {
Update::CallbackQuery(cb) => {
    let data = cb.data().unwrap_or("");

    match data {
        "vote:yes" => cb.answer().text("✅ Voted yes!").send(&client).await?,
        "vote:no"  => cb.answer().text("❌ Voted no").send(&client).await?,
        _          => cb.answer().send(&client).await?,  // empty answer
    }
}
}

CallbackQuery fields

#![allow(unused)]
fn main() {
cb.query_id       // i64: must be passed to answer_callback_query
cb.user_id        // i64: who pressed the button
cb.msg_id         // Option<i32>: message the button was on
cb.data()         // Option<&str>: the callback data string
cb.inline_msg_id  // Option<tl::enums::InputBotInlineMessageID>: for inline messages
}

Answer builder (fluent API)

cb.answer() returns an Answer builder. Chain modifiers then call .send(&client).

#![allow(unused)]
fn main() {
// Toast notification (default)
cb.answer()
    .text("✅ Done!")
    .send(&client)
    .await?;

// Alert popup (modal dialog)
cb.answer()
    .alert("⛔ You don't have permission for this action.")
    .send(&client)
    .await?;

// Open a URL (Telegram shows a confirmation first)
cb.answer()
    .url("https://example.com/auth")
    .send(&client)
    .await?;

// Silent answer (no notification, just clears the spinner)
cb.answer().send(&client).await?;
}

Answer methods

Convenience shortcuts

#![allow(unused)]
fn main() {
// Flat answer with optional text
cb.answer_flat(&client, Some("✅ Done")).await?;
cb.answer_flat(&client, None).await?;  // silent

// Alert shortcut
cb.answer_alert(&client, "⛔ Access denied").await?;
}

Via Client directly

#![allow(unused)]
fn main() {
// answer_callback_query(query_id, text, alert)
client.answer_callback_query(cb.query_id, Some("✅ Done!"), false).await?;
client.answer_callback_query(cb.query_id, Some("⛔ No!"), true).await?;  // alert
client.answer_callback_query(cb.query_id, None, false).await?;  // silent
}

Edit the message on callback

#![allow(unused)]
fn main() {
Update::CallbackQuery(cb) => {
    // Answer first (clears spinner)
    cb.answer().text("Loading…").send(&client).await?;

    // Then edit the original message
    if let Some(msg_id) = cb.msg_id {
        client.edit_message(
            // peer from the callback: resolve from context
            peer.clone(),
            msg_id,
            "Updated content",
        ).await?;
    }
}
}

Full example: vote bot

#![allow(unused)]
fn main() {
Update::CallbackQuery(cb) => {
    match cb.data().unwrap_or("") {
        "vote:yes" => {
            cb.answer().text("Thanks for voting Yes! 👍").send(&client).await?;
        }
        "vote:no" => {
            cb.answer().text("Thanks for voting No! 👎").send(&client).await?;
        }
        "vote:info" => {
            cb.answer()
                .url("https://example.com/vote-info")
                .send(&client)
                .await?;
        }
        _ => {
            cb.answer().send(&client).await?; // always answer
        }
    }
}
}

Inline Mode

Inline mode lets users type @yourbot query in any chat and receive results. ferogram supports both sides: receiving queries (bot) and sending queries (user account).

Receiving inline queries (bot side)

Via update stream

#![allow(unused)]
fn main() {
Update::InlineQuery(iq) => {
    let query    = iq.query();    // &str: what the user typed
    let query_id = iq.query_id;  // i64: must be passed to answer_inline_query

    let results = vec![
        tl::enums::InputBotInlineResult::InputBotInlineResult(
            tl::types::InputBotInlineResult {
                id:    "1".into(),
                r#type: "article".into(),
                title: Some("Result title".into()),
                description: Some(query.to_string()),
                url: None, thumb: None, content: None,
                send_message: tl::enums::InputBotInlineMessage::Text(
                    tl::types::InputBotInlineMessageText {
                        no_webpage: false, invert_media: false,
                        message: query.to_string(),
                        entities: None, reply_markup: None,
                    },
                ),
            },
        ),
    ];

    // cache_time: seconds, is_personal: false, next_offset: None
    client.answer_inline_query(query_id, results, 30, false, None).await?;
}
}

Via InlineQueryIter

For a more structured approach, use the dedicated iterator:

#![allow(unused)]
fn main() {
use ferogram::inline_iter::InlineQueryIter;

let mut iter = client.iter_inline_queries();
while let Some(iq) = iter.next().await {
    println!("Query: {}", iq.query());
    // answer it...
}
}

InlineQueryIter is backed by the update stream: it filters and yields only InlineQuery updates.

InlineQuery fields

#![allow(unused)]
fn main() {
iq.query()       // &str: the search text
iq.query_id      // i64
iq.user_id       // i64: who sent the query
iq.offset        // String: pagination offset
iq.peer          // Option<tl::enums::Peer>: chat context the user is in (None if not shared)
}

peer is populated when the bot has access to the chat - use it to tailor results per chat type.

Receiving inline sends (bot side)

When a user selects a result from your bot’s inline mode, you get Update::InlineSend:

#![allow(unused)]
fn main() {
Update::InlineSend(is) => {
    println!("User {} chose result '{}'", is.user_id, is.id);
    println!("Original query: {}", is.query);
    // is.msg_id is Some(...) when the message is still editable
}
}

InlineSend fields

Editing the sent inline message

#![allow(unused)]
fn main() {
Update::InlineSend(is) => {
    is.edit_message(&client, updated_msg).await?;
}
}

Sending inline queries (user account side)

A user account can invoke another bot’s inline mode with client.inline_query() and iterate the results:

#![allow(unused)]
fn main() {
use ferogram::inline_iter::InlineResultIter;

let mut iter = client
    .inline_query("@gif", "cute cats")
    .peer(input_peer_for_target_chat)
    .await?;

while let Some(result) = iter.next().await? {
    println!("Result: {:?}: {:?}", result.id(), result.title());

    // Send the first result to a chat
    result.send(target_peer.clone()).await?;
    break;
}
}

InlineResult methods

InlineResultIter methods

answer_inline_query parameters

#![allow(unused)]
fn main() {
client.answer_inline_query(
    query_id,   // i64: from InlineQuery
    results,    // Vec<InputBotInlineResult>
    30,         // cache_time: i32: seconds to cache results
    false,      // is_personal: bool: different results per user?
    None,       // next_offset: Option<String>: for pagination
).await?;
}

Guest Chat Queries

Update::GuestChatQuery fires when a user invites the bot into a guest-chat context (updateBotGuestChatQuery). Bots only.

Receiving the update

#![allow(unused)]
fn main() {
use ferogram::update::Update;

while let Some(update) = stream.next().await {
    if let Update::GuestChatQuery(q) = update {
        println!("query_id: {}", q.query_id);
        println!("from: {:?}", q.message.sender_id());
        println!("text: {}", q.message.text());
    }
}
}

GuestChatQuery derefs to IncomingMessage, so all the usual accessors (text(), sender_id(), chat_id(), date(), etc.) work directly on q.

Fields

Answering

Call q.answer() to get a GuestChatAnswer builder, then call .send(&client).

#![allow(unused)]
fn main() {
if let Update::GuestChatQuery(q) = update {
    q.answer()
        .article("My result")
        .text("Answer body")
        .send(&client)
        .await?;
}
}

Result kinds

Message content

Other builder methods

Checking if a bot supports guest chat

In the User type, bot_guestchat (flags2.19) is set when the bot has declared guest-chat support. This is a Layer 225 addition.

Middleware & Dispatcher

ferogram ships a Dispatcher that routes incoming updates to typed handlers, and a middleware chain that intercepts every update before it reaches any handler.

Dispatcher basics

#![allow(unused)]
fn main() {
use ferogram::filters::{self, Dispatcher};

let mut dp = Dispatcher::new();

// Handle /start command (bots)
dp.on_message(filters::command("start"), |msg| async move {
    msg.reply("Hello!").await.ok();
});

// Handle any private text
dp.on_message(filters::private() & filters::text(), |msg| async move {
    let echo = msg.text().unwrap_or_default().to_string();
    msg.reply(echo).await.ok();
});

// Drive the dispatcher from the update stream
let mut stream = client.stream_updates();
while let Some(upd) = stream.next().await {
    dp.dispatch(upd).await;
}
}

dispatch is async and runs handlers serially per update. For concurrent handling, spawn each dispatch call:

#![allow(unused)]
fn main() {
use std::sync::Arc;

let dp = Arc::new(dp);
let mut stream = client.stream_updates();
while let Some(upd) = stream.next().await {
    let dp = dp.clone();
    tokio::spawn(async move { dp.dispatch(upd).await; });
}
}

Built-in filters

All filters return a BoxFilter which supports & (AND), | (OR), and ! (NOT).

Combining filters

#![allow(unused)]
fn main() {
// Both conditions must be true
let f = filters::private() & filters::text();

// Either condition must be true
let f = filters::command("help") | filters::command("start");

// Negate a filter
let f = !filters::forwarded();

// Complex expressions
let f = (filters::group() | filters::channel()) & !filters::forwarded();
}

Dispatcher methods

Routers

Router lets you split a large bot into feature modules with their own handlers and optional scoped filters.

#![allow(unused)]
fn main() {
use ferogram::filters::{Router, command, private};

pub fn admin_router() -> Router {
    let mut r = Router::new();
    // Only handle /ban and /kick from private chats
    r.scope(private());
    r.on_message(command("ban"),  handle_ban);
    r.on_message(command("kick"), handle_kick);
    r
}

// In main:
dp.include(admin_router());
}

scope(filter) adds a guard that runs before any handler in the router. If the filter does not match, the router is skipped entirely.

Middleware

Middleware intercepts every Update before it reaches a handler. Common use cases include logging, rate-limiting, authentication, and metrics.

Implementing Middleware

#![allow(unused)]
fn main() {
use ferogram::middleware::{Middleware, Next, BoxFuture, DispatchResult};
use ferogram::update::Update;

struct LoggingMiddleware;

impl Middleware for LoggingMiddleware {
    fn call(&self, update: Update, next: Next) -> BoxFuture {
        Box::pin(async move {
            println!("Update: {:?}", update);
            let result = next.run(update).await;
            if let Err(ref e) = result {
                println!("Handler error: {e}");
            }
            result
        })
    }
}
}

Registering middleware

#![allow(unused)]
fn main() {
dp.middleware(LoggingMiddleware);
}

Middleware runs in registration order: the first middleware() call wraps the outermost layer.

Next

Next represents the remainder of the chain. Call next.run(update).await to pass control forward. If you do not call it, all remaining middleware and the handler are skipped.

#![allow(unused)]
fn main() {
impl Middleware for AuthMiddleware {
    fn call(&self, update: Update, next: Next) -> BoxFuture {
        Box::pin(async move {
            if let Update::NewMessage(ref msg) = update {
                if !is_allowed(msg.sender_user_id()) {
                    return Ok(()); // block: do not call next
                }
            }
            next.run(update).await
        })
    }
}
}

Closure middleware

For simple cases, pass a closure directly via the middleware_fn helper (if available) or wrap in a newtype:

#![allow(unused)]
fn main() {
struct TimerMiddleware;

impl Middleware for TimerMiddleware {
    fn call(&self, update: Update, next: Next) -> BoxFuture {
        Box::pin(async move {
            let start = std::time::Instant::now();
            let result = next.run(update).await;
            println!("Handled in {:?}", start.elapsed());
            result
        })
    }
}

dp.middleware(TimerMiddleware);
}

Full example: rate-limiter middleware

#![allow(unused)]
fn main() {
use dashmap::DashMap;
use ferogram::middleware::{BoxFuture, DispatchResult, Middleware, Next};
use ferogram::update::Update;
use std::sync::Arc;
use std::time::{Duration, Instant};

struct RateLimiter {
    last_seen: Arc<DashMap<i64, Instant>>,
    period: Duration,
}

impl RateLimiter {
    fn new(period: Duration) -> Self {
        Self { last_seen: Arc::new(DashMap::new()), period }
    }
}

impl Middleware for RateLimiter {
    fn call(&self, update: Update, next: Next) -> BoxFuture {
        let last_seen = self.last_seen.clone();
        let period = self.period;
        Box::pin(async move {
            if let Update::NewMessage(ref msg) = update {
                if let Some(uid) = msg.sender_user_id() {
                    let now = Instant::now();
                    if let Some(t) = last_seen.get(&uid) {
                        if now.duration_since(*t) < period {
                            return Ok(()); // drop: too fast
                        }
                    }
                    last_seen.insert(uid, now);
                }
            }
            next.run(update).await
        })
    }
}

// Register: limit each user to one message per second
dp.middleware(RateLimiter::new(Duration::from_secs(1)));
}

Handler signatures

All handlers must be async fn or closures returning a Future:

#![allow(unused)]
fn main() {
// No arguments (ignores the message)
dp.on_message(filters::command("ping"), || async {
    // nothing
});

// Message only
dp.on_message(filters::text(), |msg| async move {
    println!("{:?}", msg.text());
});
}

The dispatcher calls handlers with msg.clone() so handlers can be registered multiple times. Handlers do not need to return a value; errors should be handled internally (e.g. .ok() on send results).

Finite State Machine (FSM)

The FSM module lets bots track per-user conversation state across multiple messages without managing a global HashMap manually. State is stored in a pluggable StateStorage backend and keyed by user ID + chat ID.

Quick start

Add the derive feature to your Cargo.toml:

ferogram = { version = "0.3", features = ["derive"] }

Define a state enum and derive FsmState:

#![allow(unused)]
fn main() {
use ferogram::FsmState;

#[derive(FsmState, Clone, Debug, PartialEq)]
enum OrderState {
    AwaitingProduct,
    AwaitingQuantity,
    AwaitingConfirmation,
}
}

Wire it into the dispatcher:

use std::sync::Arc;
use ferogram::{Client, filters, fsm::MemoryStorage};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (client, _sd) = Client::builder()
        .api_id(12345)
        .api_hash("your_hash")
        .session("bot.session")
        .connect()
        .await?;

    client.bot_sign_in("TOKEN").await?;
    client.save_session().await?;

    let mut dp = filters::Dispatcher::new();
    dp.with_state_storage(Arc::new(MemoryStorage::new()));

    // Entry point - no active state yet
    dp.on_message(filters::command("order"), |msg| async move {
        msg.reply("What product would you like?").await.ok();
    });

    // Triggered only when the user is in AwaitingProduct
    dp.on_message_fsm(filters::text(), OrderState::AwaitingProduct, |msg, state| async move {
        let product = msg.text().unwrap_or_default().to_string();
        state.set_data("product", &product).await.ok();
        state.transition(OrderState::AwaitingQuantity).await.ok();
        msg.reply("How many?").await.ok();
    });

    dp.on_message_fsm(filters::text(), OrderState::AwaitingQuantity, |msg, state| async move {
        let qty = msg.text().unwrap_or_default().to_string();
        let product: String = state.get_data("product").await.unwrap_or_default();
        state.transition(OrderState::AwaitingConfirmation).await.ok();
        msg.reply(format!("Order {} × {}. Confirm? (yes/no)", qty, product)).await.ok();
    });

    dp.on_message_fsm(filters::text(), OrderState::AwaitingConfirmation, |msg, state| async move {
        match msg.text().unwrap_or("").trim() {
            "yes" => {
                state.clear_state().await.ok();
                msg.reply("Order placed!").await.ok();
            }
            _ => {
                state.clear_state().await.ok();
                msg.reply("Order cancelled.").await.ok();
            }
        }
    });

    let mut stream = client.stream_updates();
    while let Some(upd) = stream.next().await {
        dp.dispatch(upd).await;
    }
    Ok(())
}

FsmState trait

Any enum that derives FsmState can be used as a state discriminant:

#![allow(unused)]
fn main() {
use ferogram::FsmState;

#[derive(FsmState, Clone, Debug, PartialEq)]
enum Form {
    Name,
    Email,
    Done,
}
}

You can also implement FsmState manually if you need custom serialization:

#![allow(unused)]
fn main() {
impl ferogram::fsm::FsmState for Form {
    fn as_key(&self) -> String {
        format!("{:?}", self)
    }
    fn from_key(key: &str) -> Option<Self> {
        match key {
            "Name" => Some(Self::Name),
            "Email" => Some(Self::Email),
            "Done" => Some(Self::Done),
            _ => None,
        }
    }
}
}

StateContext

Handler functions registered via on_message_fsm receive a StateContext as the second argument. It provides the following methods:

set_data / get_data use serde_json internally, so any Serialize + DeserializeOwned type works.

State key strategies

By default, state is tracked per user per chat. Change the strategy on the dispatcher:

#![allow(unused)]
fn main() {
use ferogram::fsm::StateKeyStrategy;

dp.with_key_strategy(StateKeyStrategy::PerUser);    // one session per user across all chats
dp.with_key_strategy(StateKeyStrategy::PerChat);    // shared state per chat (e.g. group games)
dp.with_key_strategy(StateKeyStrategy::PerUserPerChat); // default
}

Storage backends

MemoryStorage (default for testing)

In-process DashMap-backed storage. State is lost on restart.

#![allow(unused)]
fn main() {
use ferogram::fsm::MemoryStorage;
use std::sync::Arc;

dp.with_state_storage(Arc::new(MemoryStorage::new()));
}

Custom backend

Implement the StateStorage trait to persist state in Redis, a database, or any store:

#![allow(unused)]
fn main() {
use ferogram::fsm::{StateStorage, StateKey, StorageError};
use async_trait::async_trait;

struct RedisStorage { /* ... */ }

#[async_trait]
impl StateStorage for RedisStorage {
    async fn get_state(&self, key: &StateKey) -> Result<Option<String>, StorageError> { todo!() }
    async fn set_state(&self, key: &StateKey, state: &str) -> Result<(), StorageError> { todo!() }
    async fn clear_state(&self, key: &StateKey) -> Result<(), StorageError> { todo!() }
    async fn get_data(&self, key: &StateKey, field: &str) -> Result<Option<String>, StorageError> { todo!() }
    async fn set_data(&self, key: &StateKey, field: &str, value: &str) -> Result<(), StorageError> { todo!() }
    async fn clear_data(&self, key: &StateKey, field: &str) -> Result<(), StorageError> { todo!() }
    async fn clear_all_data(&self, key: &StateKey) -> Result<(), StorageError> { todo!() }
}
}

Handler signature

FSM handlers take two arguments: the message and the state context:

#![allow(unused)]
fn main() {
dp.on_message_fsm(filter, MyState::SomeVariant, |msg, state| async move {
    // msg  : ferogram::update::IncomingMessage
    // state: ferogram::fsm::StateContext
});
}

For edited messages use on_edit_fsm with the same signature.

Routers with FSM

Routers support FSM handlers too, which is useful for splitting a bot into feature modules:

#![allow(unused)]
fn main() {
use ferogram::filters::Router;
use std::sync::Arc;

fn order_router() -> Router {
    let mut r = Router::new();
    r.on_message_fsm(filters::text(), OrderState::AwaitingProduct, handle_product);
    r.on_message_fsm(filters::text(), OrderState::AwaitingQuantity, handle_qty);
    r
}

// Then include in the dispatcher:
dp.include(order_router());
}

Conversation API

The Conversation type provides a high-level, blocking-style interface for multi-step bot flows: send a question, wait for the answer, send the next question, and so on - all within a single async fn, without manually tracking state.

Conversation wraps a mutable reference to an UpdateStream and filters updates to a single peer. Updates from other peers are buffered internally and can be retrieved with drain_buffered().

Quick start

#![allow(unused)]
fn main() {
use std::time::Duration;
use ferogram::conversation::Conversation;

// In a handler or task that already owns the update stream:
let mut conv = Conversation::new(&client, &mut stream, "@username").await?;

conv.ask("What is your name?").await?;
let name_msg = conv.get_response(Duration::from_secs(60)).await?;
let name = name_msg.text().unwrap_or("unknown").to_string();

conv.ask(format!("Nice to meet you, {}! How old are you?", name)).await?;
let age_msg = conv.get_response(Duration::from_secs(60)).await?;
let age = age_msg.text().unwrap_or("?").to_string();

conv.respond(format!("Got it: {} is {} years old.", name, age)).await?;
}

Creating a Conversation

#![allow(unused)]
fn main() {
use ferogram::conversation::Conversation;

let mut conv = Conversation::new(&client, &mut stream, peer).await?;
}

peer accepts anything that implements Into<PeerRef>: a &str username, a numeric ID, or a resolved tl::enums::Peer.

Sending messages

Both accept any Into<String>.

Waiting for responses

deadline is a std::time::Duration. If no response arrives within the deadline, the method returns ConversationError::Timeout.

Non-matching updates (from other peers, or update types other than NewMessage / CallbackQuery) are buffered. Retrieve them with:

#![allow(unused)]
fn main() {
let leftover: Vec<Update> = conv.drain_buffered();
}

Error handling

#![allow(unused)]
fn main() {
use ferogram::conversation::ConversationError;

match conv.get_response(Duration::from_secs(30)).await {
    Ok(msg) => { /* process msg */ }
    Err(ConversationError::Timeout(d)) => {
        conv.respond("You took too long! Please try again.").await.ok();
    }
    Err(ConversationError::StreamClosed) => { /* bot is shutting down */ }
    Err(ConversationError::Invocation(e)) => { return Err(e.into()); }
}
}

Button interaction example

#![allow(unused)]
fn main() {
use std::time::Duration;
use ferogram::{InputMessage, keyboard::{Button, InlineKeyboard}};
use ferogram::conversation::Conversation;

let mut conv = Conversation::new(&client, &mut stream, peer).await?;

let kb = InlineKeyboard::new()
    .row([
        Button::callback("✅ Yes", b"yes"),
        Button::callback("❌ No",  b"no"),
    ]);

conv.ask(InputMessage::text("Confirm your order?").keyboard(kb)).await?;

let click = conv.wait_click(Duration::from_secs(120)).await?;
match click.data().unwrap_or("") {
    "yes" => conv.respond("Order confirmed!").await?,
    _     => conv.respond("Order cancelled.").await?,
};
}

Integrating with the dispatcher

Because Conversation borrows &mut UpdateStream exclusively, you typically use it in a handler that was given the stream, or spin up a dedicated task:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use tokio::sync::Mutex;

// Give one user their own conversation task
let stream = Arc::new(Mutex::new(client.stream_updates()));

// … in a handler triggered by /start:
let client2 = client.clone();
let stream2 = stream.clone();
let user_peer = msg.peer_id().cloned().unwrap();

tokio::spawn(async move {
    let mut locked = stream2.lock().await;
    if let Ok(mut conv) = Conversation::new(&client2, &mut locked, user_peer).await {
        run_onboarding(&mut conv).await.ok();
    }
});
}

For multi-user bots, the FSM approach is usually a better fit - see FSM. Use Conversation when the flow is short and you need the simplicity of sequential await calls.

Full example: simple registration flow

#![allow(unused)]
fn main() {
use std::time::Duration;
use ferogram::conversation::{Conversation, ConversationError};

async fn registration_flow(
    client: &ferogram::Client,
    stream: &mut ferogram::UpdateStream,
    peer: ferogram::tl::enums::Peer,
) -> Result<(), ConversationError> {
    let mut conv = Conversation::new(client, stream, peer).await?;
    let timeout = Duration::from_secs(120);

    conv.ask("Welcome! Please enter your first name:").await?;
    let first = conv.get_response(timeout).await?;
    let first_name = first.text().unwrap_or("").trim().to_string();
    if first_name.is_empty() {
        conv.respond("Name cannot be empty. Please /start again.").await?;
        return Ok(());
    }

    conv.ask("Great! Now your email address:").await?;
    let email_msg = conv.get_response(timeout).await?;
    let email = email_msg.text().unwrap_or("").trim().to_string();

    conv.respond(format!(
        "Registered: {} <{}>. Welcome aboard!", first_name, email
    )).await?;

    Ok(())
}
}

Client Methods: Full Reference

All methods on Client. Every method is async and returns Result<T, InvocationError> unless noted.

Connection & Session

let cfg = Config {
    api_id:   12345,
    api_hash: "abc".into(),
    catch_up: true,
    ..Config::with_string_session(std::env::var("SESSION").unwrap_or_default())
};
let (client, _token) = Client::connect(cfg).await?;

let s = client.export_session_string().await?;
std::env::set_var("TG_SESSION", &s);

Authentication

Updates

let mut updates = client.stream_updates();
while let Some(update) = updates.next().await {
    match update {
        Update::NewMessage(msg) => { /* … */ }
        _ => {}
    }
}

Messaging

Reactions

use ferogram::reactions::InputReactions;
client.send_reaction(peer, msg_id, InputReactions::emoticon(“👍”)).await?;
client.send_reaction(peer, msg_id, InputReactions::remove()).await?; // remove all
client.send_reaction(peer, msg_id, InputReactions::emoticon(“🔥”).big()).await?;
See Reactions for the full guide.




async
client.get_reactions(peer: impl Into<PeerRef>, msg_ids: Vec<i32>) → Result<(), InvocationError>


Trigger a server push of the current reaction counters for the given message IDs. The server responds with updateMessageReactions updates in the stream.





async
client.iter_reaction_users(peer: impl Into<PeerRef>, msg_id: i32, reaction: Option<tl::enums::Reaction>, limit: i32, offset: Option<String>) → Result<tl::types::messages::MessageReactionsList, InvocationError>


Get the list of users who reacted to a message. Pass reaction = None for all reactions. limit max 100; use offset from the previous response to paginate.





async
client.send_paid_reaction(peer: impl Into<PeerRef>, msg_id: i32, count: i32) → Result<(), InvocationError>


Send a paid (Stars) reaction to a message. count is the number of Stars to spend.





async
client.read_reactions(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Mark all unread reactions in a chat as seen (clears reaction badges).





async
client.clear_recent_reactions() → Result<(), InvocationError>


Clear the recent reactions list shown in the reaction picker.




Sending chat actions


async
client.send_chat_action(peer: Peer, action: SendMessageAction) → Result<(), InvocationError>



Send a one-shot typing / uploading / recording indicator. Expires after ~5 seconds. Use TypingGuard to keep it alive for longer operations. top_msg_id restricts the indicator to a forum topic.





Search


sync
client.search(peer: impl Into<PeerRef>, query: &str) → SearchBuilder


Returns a SearchBuilder for per-peer message search with date filters, sender filter, media type filter, and pagination.





sync
client.search_global_builder(query: &str) → GlobalSearchBuilder


Returns a GlobalSearchBuilder for searching across all dialogs simultaneously.





async
client.search(peer: impl Into<PeerRef>) → SearchBuilder


Build a message search for a peer. Chain .query(), .limit(), .filter(), etc., then call .collect(&client).await? to run it. For a one-shot query, use client.search().query("text").collect(&client).await?.





async
client.search_global(query: &str, limit: i32) → Result<Vec<IncomingMessage>, InvocationError>


Simple one-shot global search. For advanced options use client.search_global_builder().




Dialogs & History


async
client.get_dialogs(limit: i32) → Result<Vec<Dialog>, InvocationError>


Fetch the most recent limit dialogs. Each Dialog has title(), peer(), unread_count(), and top_message().





sync
client.iter_dialogs() → DialogIter


Lazy iterator that pages through all dialogs automatically. Call iter.next(&client).await?. iter.total() returns the server-reported count after the first page.





sync
client.iter_messages(peer: impl Into<PeerRef>) → MessageIter


Lazy iterator over the full message history of a peer, newest first. Call iter.next(&client).await?.





async
client.get_message_history(peer: impl Into<PeerRef>, limit: i32, offset_id: i32) → Result<Vec<IncomingMessage>, InvocationError>


Fetch a page of messages. Pass the lowest message ID from the previous page as offset_id to paginate.





async
client.mark_read(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Mark all messages in a dialog as read.





async
client.clear_mentions(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Clear unread @mention badges in a chat.





async
client.delete_dialog(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Delete a dialog from the account's dialog list (does not delete messages for others).





async
client.delete_chat_history(peer: impl Into<PeerRef>, max_id: i32, revoke: bool) → Result<(), InvocationError>


Delete message history up to max_id. Pass max_id = 0 to delete everything. revoke = true also removes messages for all other participants (requires admin rights in channels).





async
client.pin_dialog(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Pin a dialog to the top of the dialog list.





async
client.pin_dialog(peer: impl Into<PeerRef>, pin: bool) → Result<(), InvocationError>


Unpin a previously pinned dialog.





async
client.get_pinned_dialogs(folder_id: i32) → Result<Vec<tl::enums::Dialog>, InvocationError>


Fetch all pinned dialogs in a folder. Use folder_id = 0 for the main list, 1 for the archive.





async
client.mark_dialog_unread(peer: impl Into<PeerRef>, unread: bool) → Result<(), InvocationError>


Manually mark a dialog as unread (true) or read (false). This sets the unread dot without actually having new messages.




Scheduled messages


async
client.get_scheduled_messages(peer: impl Into<PeerRef>) → Result<Vec<IncomingMessage>, InvocationError>


Fetch all messages currently scheduled in a chat.





async
client.delete_scheduled_messages(peer: impl Into<PeerRef>, ids: Vec<i32>) → Result<(), InvocationError>


Cancel and delete scheduled messages by their scheduled message IDs.





async
client.send_scheduled_now(peer: impl Into<PeerRef>, ids: Vec<i32>) → Result<(), InvocationError>


Immediately deliver one or more scheduled messages. ids are the scheduled message IDs returned by get_scheduled_messages.




Participants & Admin


async
client.get_participants(peer: impl Into<PeerRef>, limit: i32) → Result<Vec<Participant>, InvocationError>


Fetch members of a chat or channel. Pass limit = 0 for the default server maximum per page. Use iter_participants to lazily page all members.





async
client.iter_participants(peer: impl Into<PeerRef>, filter: Option<tl::enums::ChannelParticipantsFilter>, limit: i32) → Result<Vec<Participant>, InvocationError>


Fetch all members of a channel or supergroup, optionally filtered and limited. Pass filter = None and limit = 0 to retrieve all members up to the server default. For basic groups use get_participants.





async
client.kick(peer: impl Into<PeerRef>, user_id: i64) → Result<(), InvocationError>


Remove a user from a group, channel, or supergroup.





async
client.ban(peer: impl Into<PeerRef>, user_id: i64, until: Option<i32>) → Result<(), InvocationError>


Ban a user from a channel or supergroup. until: None is permanent; Some(ts) bans until that Unix timestamp. To unban, use restrict with an empty BannedRightsBuilder.





async
client.set_admin(peer: impl Into<PeerRef>, user_id: i64, rights: AdminRightsBuilder) → Result<(), InvocationError>


Set admin rights. Use AdminRightsBuilder::full_admin() to promote or AdminRightsBuilder::new() to demote.





async
client.set_admin(peer: impl Into<PeerRef>, user_id: i64, rights: AdminRightsBuilder) → Result<(), InvocationError>


Promote a user to admin with specified rights. See Admin & Ban Rights.





async
client.restrict(peer: impl Into<PeerRef>, user_id: i64, rights: BannedRightsBuilder) → Result<(), InvocationError>


Restrict or ban a user. Pass BannedRightsBuilder::full_ban() to fully ban. See Admin & Ban Rights.





async
client.get_profile_photos(peer: impl Into<PeerRef>, limit: i32) → Result<Vec<tl::enums::Photo>, InvocationError>


Fetch a page of a user's profile photos.





async
client.iter_profile_photos(peer: impl Into<PeerRef>, chunk_size: i32) → Result<ProfilePhotoIter, InvocationError>


Lazy iterator over all profile photos of a user, fetched in pages of chunk_size. Pass chunk_size = 0 for the default (100). Call iter.next().await? to advance. Only works for users.





async
client.search_peer(query: &str) → Result<Vec<tl::enums::Peer>, InvocationError>


Search for a peer (user, group, or channel) by name prefix. Searches contacts, dialogs, and globally. Returns combined results.





async
client.get_permissions(peer: impl Into<PeerRef>, user_id: i64) → Result<ParticipantPermissions, InvocationError>


Fetch the effective permissions of a user in a channel or supergroup. See Participants & Members.




Media


async
client.upload_file(path: impl AsRef<Path>) → Result<UploadedFile, InvocationError>



Upload a file from disk. Stats the file for optimal part sizing; uses parallel workers and saveBigFilePart for files over 10 MB automatically. Returns an UploadedFile.
let data = std::fs::read("photo.jpg")?;
let uploaded = client.upload_file("/tmp/photo.jpg").await?;
let media = uploaded.as_photo_media();







async
client.send_file(peer: tl::enums::Peer, media: tl::enums::InputMedia, caption: &str) → Result<(), InvocationError>


Send an uploaded file as a photo or document. caption is the message text shown below the media; pass "" for no caption (it is not Option).





async
client.send_album(peer: tl::enums::Peer, items: Vec<AlbumItem>) → Result<(), InvocationError>



Send 2-10 media items as a grouped album. Each AlbumItem carries its own caption and optional reply_to. See AlbumItem for builder details.
use ferogram::media::AlbumItem;
client.send_album(peer, vec![
    AlbumItem::new(photo1).caption("First"),
    AlbumItem::new(photo2).caption("Second"),
]).await?;







async
client.download(media: &MessageMedia, dest: impl AsyncWrite + Unpin) → Result<u64, InvocationError>


Download a media file and write it to path. The path argument accepts anything that implements AsRef<Path> (e.g. &str, String, PathBuf). DC routing is handled automatically.




Callbacks & Inline


async
client.answer_callback_query(query_id: i64, text: Option<&str>, alert: bool) → Result<(), InvocationError>


Acknowledge an inline button press. text shows a toast (or alert if alert=true). Must be called within 60 seconds of the button press.





async
client.answer_inline_query(query_id: i64, results: Vec<InputBotInlineResult>, cache_time: i32, is_personal: bool, next_offset: Option<&str>) → Result<(), InvocationError>


Respond to an inline query with a list of results. cache_time in seconds. Empty result list now handled correctly (fixed in v0.2.0).




Peer resolution


async
client.resolve<P: Into<PeerRef>>(peer: P) → Result<tl::enums::Peer, InvocationError>



Resolve any peer reference to a Peer. Accepts all PeerRef input types:

&str / String: "@username", "me", "self", numeric string, t.me/ URL, invite link, E.164 phone

i64 / i32: Bot-API encoded numeric ID

tl::enums::Peer: returned as-is, zero cost

tl::enums::InputPeer: access hash cached, then stripped to Peer



Resolution is cache-first; an RPC is only made on a cache miss.






async
client.resolve(peer: &str) → Result<tl::enums::Peer, InvocationError>


String-only variant of resolve(). Accepts "@username", "+phone", "me", numeric string, t.me/ URL, and invite links. Prefer resolve() when the input may not be a string.





async
client.resolve_to_input_peer(peer: &tl::enums::Peer) → Result<tl::enums::InputPeer, InvocationError>


Convert a bare Peer to an InputPeer with access hash. Returns an error if the peer has not been seen in a prior API call and the hash is unknown.




Raw API


async
client.invoke<R: RemoteCall>(req: &R) → Result<R::Return, InvocationError>



Call any Layer 225 API method directly. See Raw API Access for the full guide.
use ferogram_tl_types::functions;
let state = client.invoke(&functions::updates::GetState {}).await?;







async
client.invoke_on_dc<R: RemoteCall>(dc_id: i32, req: &R) → Result<R::Return, InvocationError>


Send a request to a specific Telegram data centre. Used for file downloads from CDN DCs.




Chat management


async
client.join_chat(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Join a group or channel by peer reference.





async
client.join_link(link: &str) → Result<(), InvocationError>


Accept a t.me/+hash or t.me/joinchat/hash invite link.





async
client.create_group(title: impl Into<String>, user_ids: Vec<i64>) → Result<tl::enums::Chat, InvocationError>


Create a new basic group with the given title and initial member list. Returns the created Chat. Basic groups support up to 200 members; migrate to supergroup with migrate_chat if you need more.





async
client.create_channel(title: impl Into<String>, about: impl Into<String>, broadcast: bool) → Result<tl::enums::Chat, InvocationError>


Create a new channel (broadcast = true) or supergroup (broadcast = false). Returns the created Chat.





async
client.delete_chat(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Permanently delete a channel or supergroup. Only the creator can do this. Irreversible.





async
client.delete_chat(chat_id: i64) → Result<(), InvocationError>


Delete a legacy basic group by its chat ID. Only the creator can do this. Use delete_chat for all peer types.





async
client.leave_chat(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Leave a channel or supergroup. For basic groups, use kick on yourself or delete_dialog to just hide it.





async
client.set_profile(peer).title(: impl Into<PeerRef>, title: impl Into<String>) → Result<(), InvocationError>


Rename a chat, group, channel, or supergroup. Works for both basic groups and channels/supergroups.





async
client.set_profile(peer).bio(: impl Into<PeerRef>, about: impl Into<String>) → Result<(), InvocationError>


Set or update the description/about text for any chat type.





async
client.set_profile(peer).chat_photo(peer: impl Into<PeerRef>, photo: tl::enums::InputChatPhoto) → Result<(), InvocationError>


Change the profile photo of a chat. Pass tl::enums::InputChatPhoto::Empty to remove the current photo.





async
client.edit_chat_default_banned_rights(peer: impl Into<PeerRef>, build: impl FnOnce(BannedRightsBuilder) → BannedRightsBuilder) → Result<(), InvocationError>



Set default permissions for all members of a group or channel via a closure:
// Disable media and polls for everyone
client.edit_chat_default_banned_rights(peer, |b| {
    b.send_media(true).send_polls(true)
}).await?;







async
client.get_chat_full(peer: impl Into<PeerRef>) → Result<tl::enums::messages::ChatFull, InvocationError>


Get the full info object for any chat type. Contains full description, pinned message ID, linked channel, member count, slow mode, and more.





async
client.migrate_chat(chat_id: i64) → Result<tl::enums::Chat, InvocationError>


Upgrade a legacy basic group to a supergroup. Returns the new channel peer. The original chat ID becomes invalid after migration.





async
client.invite_users(peer: impl Into<PeerRef>, user_ids: Vec<i64>) → Result<(), InvocationError>


Add one or more users to a chat. For channels all users are added in one request; for basic groups each user is added individually.





async
client.set_history_ttl(peer: impl Into<PeerRef>, period: i32) → Result<(), InvocationError>


Set the auto-delete timer for a chat. period is in seconds. Common values: 86400 (1 day), 604800 (1 week), 2678400 (1 month). Pass 0 to disable.





async
client.get_common_chats(user_id: i64, max_id: i64, limit: i32) → Result<Vec<tl::enums::Chat>, InvocationError>


Get chats shared between the logged-in account and user_id. Pass max_id = 0 for the first page. Max limit is 100.





async
client.get_online_count(peer: impl Into<PeerRef>) → Result<i32, InvocationError>


Get the approximate number of members currently online in a group or channel.





async
client.toggle_no_forwards(peer: impl Into<PeerRef>, enabled: bool) → Result<(), InvocationError>


Enable or disable the no-forwards restriction. When enabled, members cannot forward messages out of this chat.





sync
Client::parse_invite_hash(link: &str) → Option<&str>


Parse the invite hash out of any t.me/+… or t.me/joinchat/… link format. Returns None if the link is not a valid invite.





async
client.set_chat_theme(peer: impl Into<PeerRef>, emoticon: impl Into<String>) → Result<(), InvocationError>


Set the emoji-based colour theme for a chat. Pass a single emoji string such as "🌈" or "❄️" to apply a theme, or an empty string to reset to default.





async
client.set_chat_reactions(peer: impl Into<PeerRef>, reactions: tl::enums::ChatReactions) → Result<(), InvocationError>



Control which reactions are allowed in a chat. Use ChatReactionsAll, ChatReactionsSome, or ChatReactionsNone.
// Allow all (including custom emoji)
client.set_chat_reactions(peer.clone(),
    tl::enums::ChatReactions::ChatReactionsAll(
        tl::types::ChatReactionsAll { allow_custom: true }
    )
).await?;
// Disable all reactions
client.set_chat_reactions(peer.clone(),
tl::enums::ChatReactions::ChatReactionsNone
).await?;




async
client.toggle_forum(peer: impl Into<PeerRef>, enabled: bool) → Result<(), InvocationError>


Enable or disable forum (topics) mode on a supergroup. Requires channel admin rights. Once enabled the group gains a General topic (ID 1) automatically. See Forum Topics for full topic management.




Advanced Messaging


async
client.forward_messages_returning(destination: impl Into<PeerRef>, message_ids: &[i32], source: impl Into<PeerRef>) → Result<Vec<IncomingMessage>, InvocationError>


Like forward_messages but returns the newly created message objects in the destination chat. Useful when you need the forwarded message IDs immediately.





async
msg.get_reply() → Option<&IncomingMessage>


Access the message this message replies to. Available directly on IncomingMessage. Returns None if not a reply. To fetch the replied-to message by ID, use client.get_messages(peer, &[id]).





async
client.get_users_by_id(ids: &[i64]) → Result<Vec<Option<User>>, InvocationError>


Bulk-fetch typed User objects by their IDs. The result is in the same order as ids; entries are None for deleted/unknown users.





async
client.get_user_full(user_id: i64) → Result<tl::types::UserFull, InvocationError>


Get the full info object for a user. Contains bio, common chats count, bot info, profile/fallback photos, privacy settings, pinned message ID, and more.





async
client.get_pinned_message(peer: impl Into<PeerRef>) → Result<Option<IncomingMessage>, InvocationError>


Fetch the currently pinned message in a chat. Returns None if nothing is pinned.





async
client.pin_message(peer: impl Into<PeerRef>, message_id: i32, silent: bool, unpin: bool, pm_oneside: bool) → Result<(), InvocationError>


Pin (or unpin) a message. Set silent = true to avoid a pin notification. pm_oneside = true pins only for the logged-in user in DMs.





async
client.pin_message(peer: impl Into<PeerRef>, id: i32, pin: bool) → Result<(), InvocationError>


Shorthand for unpinning a specific message (calls pin_message with unpin = true).





async
client.unpin_all_messages(peer: impl Into<PeerRef>) → Result<(), InvocationError>


Unpin every pinned message in a chat at once.





async
client.get_message_read_participants(peer: impl Into<PeerRef>, msg_id: i32) → Result<Vec<tl::types::ReadParticipantDate>, InvocationError>


Get the list of users who have read a specific message and the time each read it. Only works in groups; returns an empty list for channels and private chats.





async
client.get_replies(peer: impl Into<PeerRef>, msg_id: i32, limit: i32, offset_id: i32) → Result<Vec<IncomingMessage>, InvocationError>


Fetch thread replies under a message. msg_id is the root message ID. Pass offset_id = 0 for the first page; use the lowest ID from the previous page to paginate. Max limit is 100.





async
client.get_discussion_message(peer: impl Into<PeerRef>, msg_id: i32) → Result<tl::types::messages::DiscussionMessage, InvocationError>


Get the linked discussion message in the comments group for a channel post. Returns the discussion metadata including unread counts and max-read IDs.





async
client.read_discussion(peer: impl Into<PeerRef>, msg_id: i32, read_max_id: i32) → Result<(), InvocationError>


Mark a discussion thread as read up to read_max_id. peer is the channel, msg_id is the root post.





async
client.get_web_page_preview(text: impl Into<String>) → Result<tl::enums::MessageMedia, InvocationError>


Generate a link preview for a URL embedded in text. Returns the MessageMedia that Telegram would attach (webpage card, article embed, video thumbnail, etc.).





async
client.upload_media(peer: impl Into<PeerRef>, media: tl::enums::InputMedia) → Result<tl::enums::MessageMedia, InvocationError>


Upload a media object to Telegram servers without sending it as a message. The returned MessageMedia can be reused in subsequent send_message calls via InputMessage::copy_media(). Distinct from upload_file  -  this works with an existing InputMedia.





async
client.export_message_link(peer: impl Into<PeerRef>, msg_id: i32, grouped: bool, thread: bool) → Result<String, InvocationError>



Get a t.me/c/… permalink for a message in a channel. grouped = true returns a link to the album group; thread = true links to the discussion thread. Only works for channels (not basic groups).






async
client.get_send_as_peers(peer: impl Into<PeerRef>) → Result<Vec<tl::enums::Peer>, InvocationError>


Get the list of identities the logged-in user can send messages as in a chat (e.g. own account, linked anonymous channel). Used to implement "send as channel" / anonymous posting.





async
client.set_default_send_as(peer: impl Into<PeerRef>, send_as_peer: impl Into<PeerRef>) → Result<(), InvocationError>


send_as_peer must be one of the peers returned by get_send_as_peers. Sets the default identity for new messages in peer.




Translation & Transcription


async
client.translate_messages(peer: impl Into<PeerRef>, msg_ids: Vec<i32>, to_lang: impl Into<String>) → Result<Vec<tl::types::TextWithEntities>, InvocationError>



Translate one or more messages to to_lang (e.g. "en", "ru"). Returns translated text in the same order as msg_ids. Requires Telegram Premium for many language pairs.






async
client.transcribe_audio(peer: impl Into<PeerRef>, msg_id: i32) → Result<tl::types::messages::TranscribedAudio, InvocationError>


Request speech-to-text transcription of a voice message or video note. Transcription may be pending on first call; poll again if result.pending == true. Requires Telegram Premium.





async
client.toggle_peer_translations(peer: impl Into<PeerRef>, disabled: bool) → Result<(), InvocationError>


Show or hide the "Translate" toolbar button for a chat. disabled = true hides it.




Admin Log


async
client.get_admin_log(peer: impl Into<PeerRef>, query: impl Into<String>, limit: i32, max_id: i64, min_id: i64) → Result<Vec<tl::types::ChannelAdminLogEvent>, InvocationError>



Fetch the admin action log for a channel or supergroup. query filters by keyword (pass "" for all events). Max limit is 100. Use max_id / min_id for pagination; pass 0 for both on the first call. Only works for channels/supergroups; returns an error for basic groups.





Drafts


async
client.save_draft(peer: impl Into<PeerRef>, text: impl Into<String>) → Result<(), InvocationError>


Save a draft message for a chat. Pass an empty string to clear the current draft.





async
client.sync_drafts() → Result<(), InvocationError>


Sync all saved drafts from the server. The server responds with updateDraftMessage updates in the update stream.





async
client.clear_all_drafts() → Result<(), InvocationError>


Delete all saved drafts across all chats at once.

ClientBuilder

ClientBuilder is the fluent, type-safe constructor for a Client connection. Obtain one via Client::builder().

Just getting started? Client::quick_connect connects and authenticates in one call with no options to think about. Come back here when you need proxies, custom transports, low memory mode, or anything else the defaults don’t cover.

use ferogram::Client;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let (client, _shutdown) = Client::builder()
        .api_id(12345)
        .api_hash("abc123")
        .session("my.session")
        .catch_up(true)
        .connect()
        .await?;
    Ok(())
}

connect() returns Result<(Client, ShutdownToken), BuilderError>. The BuilderError can be MissingApiId, MissingApiHash, or a network-level Connect(InvocationError).

Common patterns

Most people only need a handful of options. Here are the three most common setups:

#![allow(unused)]
fn main() {
use ferogram::Client;

// 99% of users - just fill in credentials and go
let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .connect().await?;

// Termux / tiny VPS - running on constrained hardware
let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .low_memory_mode(true)
    .connect().await?;

// Power user - custom update queue to handle high-traffic bots
use ferogram::update_config::OverflowStrategy;

let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .update_queue_capacity(512)
    .update_overflow_strategy(OverflowStrategy::DropNewest)
    .connect().await?;
}

The full option reference follows below.

Credentials

Session

Three session backends are available. They are mutually exclusive - the last call wins.

.session("mybot.session")

.session_string(std::env::var("SESSION").unwrap_or_default())

#[cfg(feature = "libsql-session")]
use ferogram::LibSqlBackend;
use std::sync::Arc;
.session_backend(Arc::new(LibSqlBackend::new(“my.db”)))
Requires the libsql-session feature for LibSqlBackend.
See Feature Flags.



Updates


sync
.catch_up(enabled: bool) → ClientBuilder



When true, replay missed updates via updates.getDifference immediately after
connecting. Useful for bots or userbots that must not miss messages during downtime.
Default: false.





Network


sync
.dc_addr(addr: impl Into<String>) → ClientBuilder



Override the first DC address. Useful when connecting to a test server.
.dc_addr("149.154.167.40:443")   // production DC 1
.dc_addr("149.154.167.40:80")    // test DC







sync
.allow_ipv6(allow: bool) → ClientBuilder



Allow IPv6 DC addresses when resolving the DC table. Default: false.






sync
.transport(kind: TransportKind) → ClientBuilder



Choose the MTProto transport framing layer.



Variant
Description


TransportKind::Abridged
Smallest overhead (default)
TransportKind::Intermediate
Compatible with more proxies
TransportKind::Obfuscated
Deep-packet-inspection resistant
TransportKind::Http
Plain HTTP wrapping



Note: when using .mtproxy() or .proxy_link(), the transport is set automatically from the secret prefix  -  do not also call .transport().






sync
.probe_transport(enabled: bool) → ClientBuilder



Race Obfuscated, Abridged, and HTTP transports in parallel and connect using
whichever completes the DH handshake first. The losing attempts are cancelled
immediately. Ideal when you don't know which transport your network or firewall
permits. Incompatible with MTProxy. Default: false.
#![allow(unused)]
fn main() {
.probe_transport(true)
}
See Transport Probing & Resilient Connect for the race schedule, timing details, and interaction with MTProxy.






sync
.resilient_connect(enabled: bool) → ClientBuilder



If direct TCP fails, retry via DNS-over-HTTPS (Mozilla + Google DoH), then
fall back to Firebase / Google special-config endpoints. Useful in restricted
networks where Telegram DCs are ISP-blocked. Default: false.
#![allow(unused)]
fn main() {
.resilient_connect(true)
}
See Transport Probing & Resilient Connect for the full fallback chain and when to combine with probe_transport.






sync
.pfs(enabled: bool) → ClientBuilder



Enable Perfect Forward Secrecy. When set, a temporary DH key bind is performed immediately after the permanent auth key is established. Traffic runs under a short-lived session key derived from that bind; the permanent key is never used to encrypt traffic directly. If the bind RPC fails for any reason, the pool falls back to the standard session without interrupting the connection.
Adds one extra DH round-trip per connection. Off by default. Enable only if your threat model requires it.
#![allow(unused)]
fn main() {
let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_hash")
    .session("bot.session")
    .pfs(true)
    .connect()
    .await?;
}





Proxy


sync
.socks5(addr: impl Into<String>) → ClientBuilder



Route all connections through a SOCKS5 proxy. Pass a "host:port" string:
.socks5("127.0.0.1:1080")







sync
.mtproxy(proxy: MtProxyConfig) → ClientBuilder



Route all connections through an MTProxy. The transport is automatically selected
from the proxy secret prefix; do not also call .transport().
Build with ferogram::parse_proxy_link(url) or construct manually.






sync
.proxy_link(url: &str) → ClientBuilder



Set an MTProxy from a https://t.me/proxy?... or tg://proxy?... link.
An empty string is a no-op. Transport is selected from the secret prefix automatically.
.proxy_link("https://t.me/proxy?server=1.2.3.4&port=443&secret=abc123")

See Proxies & Transports for full details.





Identity (InitConnection)
These strings are sent to Telegram in the InitConnection call and appear in
the active sessions list on my.telegram.org.


sync
.device_model(model: impl Into<String>) → ClientBuilder


Device model shown in sessions. Default: "Linux".
Example: .device_model("Pixel 9 Pro")





sync
.system_version(version: impl Into<String>) → ClientBuilder


OS / system version shown in sessions. Default: "1.0".
Example: .system_version("Android 15")





sync
.app_version(version: impl Into<String>) → ClientBuilder


App version shown in sessions. Default: the crate version from CARGO_PKG_VERSION.





sync
.lang_code(code: impl Into<String>) → ClientBuilder


BCP-47 language code sent in InitConnection. Default: "en".





sync
.system_lang_code(code: impl Into<String>) → ClientBuilder


System language code. Default: "en".





sync
.lang_pack(pack: impl Into<String>) → ClientBuilder


Language pack name. Default: "" (empty). Leave unset unless building a client that mirrors an official Telegram app.




Retry & Restart


sync
.retry_policy(policy: Arc<dyn RetryPolicy>) → ClientBuilder



Override the flood-wait / rate-limit retry strategy.
The default is AutoSleep: automatically sleep for FLOOD_WAIT durations.
See Retry & Flood Wait.






sync
.restart_policy(policy: Arc<dyn ConnectionRestartPolicy>) → ClientBuilder



Override the reconnect behaviour after a connection drop. The default is
NeverRestart: the event loop exits on disconnect and the shutdown
signal fires. Use FixedInterval for automatic reconnection, or
implement the trait for custom backoff logic.
#![allow(unused)]
fn main() {
use std::sync::Arc;
use std::time::Duration;
use ferogram::FixedInterval;

// Reconnect 5 seconds after any drop
.restart_policy(Arc::new(FixedInterval {
    interval: Duration::from_secs(5),
}))
}
See Connection Restart Policy for all built-in types, custom implementation, and scheduled periodic restarts.





Experimental Features


sync
.experimental_features(features: ExperimentalFeatures) → ClientBuilder



Opt in to experimental behaviours that deviate from strict Telegram spec.
All flags default to false. Always use ..Default::default()
to stay forward-compatible with new flags.
#![allow(unused)]
fn main() {
use ferogram::{Client, ExperimentalFeatures};

Client::builder()
    .api_id(12345)
    .api_hash("abc")
    .experimental_features(ExperimentalFeatures {
        allow_zero_hash: true,  // bots only: allow hash=0 on cache miss
        ..Default::default()
    })
    .connect()
    .await?;
}
See Experimental Features for all flags, safety constraints, and when to use each one.





Terminal Methods


sync
.build() → Result<Config, BuilderError>



Build the Config struct without establishing a network connection. Useful if
you want to pass the Config to Client::connect(config) manually, or to
inspect the built configuration.






async
.connect() → Result<(Client, ShutdownToken), BuilderError>



Build the Config and connect in one step. Returns
Err(BuilderError::MissingApiId) or Err(BuilderError::MissingApiHash)
before attempting any network I/O if required fields are absent.





BuilderError



Variant
Meaning


BuilderError::MissingApiId
.api_id() was not called (or set to 0)
BuilderError::MissingApiHash
.api_hash() was not called (or left empty)
BuilderError::Connect(InvocationError)
Network / MTProto connection failed



#![allow(unused)]
fn main() {
match client_result {
    Err(BuilderError::MissingApiId) => eprintln!("Set API_ID"),
    Err(BuilderError::MissingApiHash) => eprintln!("Set API_HASH"),
    Err(BuilderError::Connect(e)) => eprintln!("Network error: {e}"),
    Ok((client, _)) => { /* use client */ }
}
}

quick_connect

Client::quick_connect connects and authenticates in a single call, handling the full auth flow interactively from stdin. If the session is already authorized the prompt is skipped entirely.

For advanced options (proxy, PFS, custom transport, catch-up, etc.) use ClientBuilder directly.

Signature

#![allow(unused)]
fn main() {
pub async fn quick_connect(
    session: impl AsRef<Path>,
    api_id: i32,
    api_hash: &str,
) -> Result<(Client, ShutdownToken), QuickConnectError>
}

Usage

use ferogram::Client;

const API_ID: i32 = 12345;
const API_HASH: &str = "your_api_hash";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _shutdown) = Client::quick_connect("my.session", API_ID, API_HASH).await?;
    // client is ready to use
    Ok(())
}

When run, the prompt sequence looks like this:

• Already signed in: no prompt, returns immediately.
• User account: asks for phone number, then login code, then 2FA password if required.
• Bot: paste a bot token (123456789:AABBcc...) instead of a phone number.

The bot token is detected automatically by its <digits>:<string> format, so the same prompt works for both users and bots.

Error Handling

QuickConnectError covers every failure mode:

#![allow(unused)]
fn main() {
use ferogram::client::QuickConnectError;

match Client::quick_connect("my.session", API_ID, API_HASH).await {
    Ok((client, _)) => { /* use client */ }
    Err(QuickConnectError::InvalidCode) => eprintln!("Wrong code, try again"),
    Err(QuickConnectError::SignUpRequired) => eprintln!("Phone not registered"),
    Err(QuickConnectError::Auth(e)) => eprintln!("Auth error: {e}"),
    Err(e) => eprintln!("Connect failed: {e}"),
}
}

quick_connect vs ClientBuilder

quick_connect and ClientBuilder connect to the same underlying transport. The difference is how much control you want.

#![allow(unused)]
fn main() {
// 99% of users - just works
let (client, _) = Client::quick_connect("bot.session", API_ID, API_HASH).await?;

// Termux / tiny VPS - memory-constrained environment
let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .low_memory_mode(true)
    .connect().await?;

// Power user with specific needs
let (client, _) = Client::builder()
    .api_id(API_ID)
    .api_hash(API_HASH)
    .session("bot.session")
    .update_queue_capacity(512)
    .update_overflow_strategy(OverflowStrategy::DropNewest)
    .connect().await?;
}

quick_connect is ClientBuilder with sensible defaults baked in and the auth flow handled for you. If you start with quick_connect and later need an option it doesn’t expose, switching to ClientBuilder is a straight drop-in: same session file, same API.

When to use ClientBuilder instead

quick_connect is intentionally minimal. Reach for ClientBuilder when you need any of the following:

• SOCKS5 or MTProxy
• Perfect Forward Secrecy (.pfs(true))
• Transport probing or resilient connect
• Custom session backend (e.g. LibSqlBackend)
• Catch-up on missed updates (.catch_up(true))
• Custom retry or reconnect policy
• Low memory mode (.low_memory_mode(true))
• Non-interactive auth (reading credentials from env vars or a config file)

Types Reference

ferogram wraps the raw TL layer’s tl::enums::User and tl::enums::Chat variants in typed structs so you never need to pattern-match bare enums.

All four types are available without any feature flags.

User

User wraps a non-empty tl::enums::User::User variant.

Construction

Identity

Flags

Online & Media

Bot-specific

Peer Conversion

User also implements Display as "Full Name (@username)" or "Full Name [id]".

Group

Group wraps a basic group (tl::types::Chat). Basic groups have ≤ 200 members; larger groups are supergroups (use Channel with megagroup() == true).

Construction

Accessors

Group implements Display as "Title [group id]".

Channel

Channel wraps both broadcast channels and supergroups (tl::types::Channel). Use kind() or megagroup() / broadcast() to distinguish them.

Construction

Identity

Kind

Flags

Rights & Media

Peer Conversion

Channel implements Display as "Title (@username)" or "Title [channel id]".

Chat (unified enum)

Chat is a convenience enum that holds either a Group or a Channel. Most client methods return peers as Chat when the type is not known in advance.

#![allow(unused)]
fn main() {
match chat {
    Chat::Group(g) => println!("Basic group: {}", g.title()),
    Chat::Channel(c) => println!("Channel/supergroup: {}", c.title()),
}
}

Construction

Common Accessors

Quick Reference

#![allow(unused)]
fn main() {
use ferogram::{User, Group, Channel, Chat};

// User
if let Some(user) = User::from_raw(raw_user) {
    println!("{} id={}", user.full_name(), user.id());
    if user.bot() { println!("It's a bot"); }
    let peer = user.as_input_peer(); // for API calls
}

// Group
if let Some(group) = Group::from_raw(raw_chat) {
    println!("{} ({} members)", group.title(), group.participants_count());
}

// Channel / Supergroup
if let Some(ch) = Channel::from_raw(raw_chat) {
    match ch.kind() {
        ferogram::ChannelKind::Broadcast => println!("Channel"),
        ferogram::ChannelKind::Megagroup => println!("Supergroup"),
        ferogram::ChannelKind::Gigagroup => println!("Gigagroup"),
    }
}

// Unified
if let Some(chat) = Chat::from_raw(raw_chat) {
    println!("id={} title={}", chat.id(), chat.title());
}
}

InputMessage Builder

InputMessage is a fluent builder for composing rich messages with full control over every parameter.

Import

#![allow(unused)]
fn main() {
use ferogram::InputMessage;
use ferogram::parsers::parse_markdown;
}

Builder methods

Plain text

#![allow(unused)]
fn main() {
let msg = InputMessage::text("Hello, world!");
client.send_message(peer, msg).await?;
}

Markdown formatting

parse_markdown converts Markdown to plain text + entity list:

#![allow(unused)]
fn main() {
let (plain, entities) = parse_markdown(
    "**Bold**, _italic_, `inline code`, and [a link](https://example.com)"
);
let msg = InputMessage::text(plain).entities(entities);
}

Supported Markdown syntax:

Reply to a message

#![allow(unused)]
fn main() {
let msg = InputMessage::text("This is my reply")
    .reply_to(Some(original_msg_id));
}

With inline keyboard

#![allow(unused)]
fn main() {
use ferogram_tl_types as tl;

let keyboard = tl::enums::ReplyMarkup::ReplyInlineMarkup(
    tl::types::ReplyInlineMarkup {
        rows: vec![
            tl::enums::KeyboardButtonRow::KeyboardButtonRow(
                tl::types::KeyboardButtonRow {
                    buttons: vec![
                        tl::enums::KeyboardButton::Callback(
                            tl::types::KeyboardButtonCallback {
                                requires_password: false,
                                style: None,
                                text: "Click me".into(),
                                data: b"my_action".to_vec(),
                            }
                        )
                    ]
                }
            )
        ]
    }
);

let msg = InputMessage::text("Pick an action:").reply_markup(keyboard);
}

Silent message (no notification)

#![allow(unused)]
fn main() {
let msg = InputMessage::text("Heads-up (no ping)").silent(true);
}

Scheduled message

#![allow(unused)]
fn main() {
use std::time::{SystemTime, UNIX_EPOCH};

// Schedule for 1 hour from now
let in_one_hour = SystemTime::now()
    .duration_since(UNIX_EPOCH).unwrap()
    .as_secs() as i32 + 3600;

let msg = InputMessage::text("This will appear in 1 hour")
    .schedule_date(Some(in_one_hour));
}

No link preview

#![allow(unused)]
fn main() {
let msg = InputMessage::text("https://example.com: visit it!")
    .no_webpage(true);
}

Combining everything

#![allow(unused)]
fn main() {
let (text, entities) = parse_markdown("📢 **Announcement:** check out _this week's update_!");

let msg = InputMessage::text(text)
    .entities(entities)
    .reply_to(Some(pinned_msg_id))
    .silent(false)
    .no_webpage(true)
    .reply_markup(keyboard);

client.send_message(channel_peer, msg).await?;
}

Peer Types

ferogram provides typed wrappers over the raw tl::enums::User and tl::enums::Chat types, and a flexible peer input system that every Client method uses automatically.

Auto-resolution

Every Client method that targets a chat, user, or channel accepts any of the following directly. You never need to pre-resolve anything.

#![allow(unused)]
fn main() {
// @username or bare username
client.send_message("@durov", "hi").await?;
client.send_message("durov", "hi").await?;

// "me" or "self": the logged-in account
client.send_message("me", "Note to self").await?;

// E.164 phone number
client.send_message("+12025551234", "hi").await?;

// t.me URL
client.send_message("https://t.me/telegram", "hi").await?;

// Invite link (must already be a member, otherwise call join_link first)
client.send_message("https://t.me/+AbCdEfGhIjKl", "hi").await?;

// Positive i64: user ID
client.send_message(12345678_i64, "hi").await?;

// Negative i64: Bot-API channel ID (-100... prefix)
client.get_message_history(-1001234567890_i64, 50, 0).await?;

// Small negative i64: basic group
client.mark_read(-123456_i64).await?;

// Raw TL peer: zero cost, no network call
use ferogram::tl;
let peer = tl::enums::Peer::User(tl::types::PeerUser { user_id: 123 });
client.send_message(peer, "hi").await?;

// Already-resolved InputPeer: hash is used directly
let ip: tl::enums::InputPeer = get_it_from_somewhere();
client.send_message(ip, "hi").await?;
}

Accepted invite link formats: https://t.me/+HASH, https://t.me/joinchat/HASH, tg://join?invite=HASH.

Resolution is cache-first. Usernames, phone numbers, and IDs that have been seen before are resolved from memory with no RPC. An RPC is only made on a genuine cache miss.

Bot-API ID encoding

Manual resolution

Use client.resolve() when you need a Peer value explicitly. It accepts all the same input types as every other Client method:

#![allow(unused)]
fn main() {
// &str: username, phone, URL, invite link
let peer = client.resolve("@username").await?;
let peer = client.resolve("+12025551234").await?;
let peer = client.resolve("https://t.me/+HASH").await?;
let peer = client.resolve("me").await?;

// i64 / i32: Bot-API numeric ID
let peer = client.resolve(12345678_i64).await?;
let peer = client.resolve(-1001234567890_i64).await?;

// tl::enums::Peer: zero cost, returned as-is
use ferogram::tl;
let raw = tl::enums::Peer::User(tl::types::PeerUser { user_id: 123 });
let peer = client.resolve(raw).await?;

// tl::enums::InputPeer: hash cached, then stripped to Peer
let ip: tl::enums::InputPeer = get_it_from_somewhere();
let peer = client.resolve(ip).await?;
}

client.resolve(peer: &str) is the string-only variant; use it when the input is always a &str. Use resolve() for everything else.

To go from a Peer back to an InputPeer (with access hash):

#![allow(unused)]
fn main() {
let input = client.resolve_to_input_peer(&peer).await?;
}

This returns an error if the peer has not appeared in any prior API response and the access hash is unknown.

Via PeerRef directly (same result):

#![allow(unused)]
fn main() {
use ferogram::PeerRef;
let peer = PeerRef::from("@username").resolve(&client).await?;
let peer = PeerRef::from(12345678_i64).resolve(&client).await?;
}

User: user account wrapper

#![allow(unused)]
fn main() {
use ferogram::types::User;

// Wrap from raw TL
if let Some(user) = User::from_raw(raw_tl_user) {
    println!("ID: {}", user.id());
    println!("Name: {}", user.full_name());
    println!("Username: {:?}", user.username());
    println!("Is bot: {}", user.bot());
    println!("Is premium: {}", user.premium());
}
}

User accessor methods

User implements Display as "Full Name (@username)" or "Full Name [user_id]".

Group: basic group wrapper

#![allow(unused)]
fn main() {
use ferogram::types::Group;

if let Some(group) = Group::from_raw(raw_tl_chat) {
    println!("ID: {}", group.id());
    println!("Title: {}", group.title());
    println!("Members: {}", group.participants_count());
    println!("I am creator: {}", group.creator());
}
}

Group accessor methods

Channel: channel / supergroup wrapper

#![allow(unused)]
fn main() {
use ferogram::types::{Channel, ChannelKind};

if let Some(channel) = Channel::from_raw(raw_tl_chat) {
    println!("ID: {}", channel.id());
    println!("Title: {}", channel.title());
    println!("Username: {:?}", channel.username());
    println!("Kind: {:?}", channel.kind());
    println!("Members: {:?}", channel.participants_count());
}
}

Channel accessor methods

ChannelKind enum

#![allow(unused)]
fn main() {
use ferogram::types::ChannelKind;

match channel.kind() {
    ChannelKind::Broadcast  => { /* Posts only, no member replies */ }
    ChannelKind::Megagroup  => { /* All members can post */ }
    ChannelKind::Gigagroup  => { /* Large public broadcast group */ }
}
}

Chat: unified chat enum

Chat unifies Group and Channel into one enum with shared accessors:

#![allow(unused)]
fn main() {
use ferogram::types::Chat;

if let Some(chat) = Chat::from_raw(raw_tl_chat) {
    println!("ID: {}", chat.id());
    println!("Title: {}", chat.title());

    match &chat {
        Chat::Group(g)   => println!("Basic group, {} members", g.participants_count()),
        Chat::Channel(c) => println!("{:?} channel", c.kind()),
    }
}
}

Chat methods

PeerExt / OptionPeerExt: extract numeric ID without match

When you have a raw tl::enums::Peer and just need the i64 ID, use the PeerExt trait instead of writing a full match block every time.

#![allow(unused)]
fn main() {
use ferogram::PeerExt;

// Instead of:
let id = match peer {
    tl::enums::Peer::User(u)    => u.user_id,
    tl::enums::Peer::Chat(c)    => c.chat_id,
    tl::enums::Peer::Channel(c) => c.channel_id,
};

// Just write:
let id = peer.bare_id();
}

OptionPeerExt adds the same .bare_id() to Option<&tl::enums::Peer>, which is what IncomingMessage::sender_id() and IncomingMessage::peer_id() return:

#![allow(unused)]
fn main() {
use ferogram::{PeerExt, OptionPeerExt};

// sender numeric ID: Option<i64>
let sender: Option<i64> = msg.sender_id().bare_id();

// chat numeric ID: Option<i64>
let chat: Option<i64> = msg.peer_id().bare_id();
}

Note: these are native Telegram IDs, not Bot-API-encoded. A channel with native ID 1234567890 is -1001234567890 in the Bot API. Use PeerRef if you need the Bot-API form.

Import summary

Participants & Members

Methods for fetching, banning, kicking, promoting, and managing chat members. All methods accept impl Into<PeerRef> for the peer argument.

Fetch participants

#![allow(unused)]
fn main() {
use ferogram::participants::Participant;

// Fetch up to N participants at once
let members: Vec<Participant> = client
    .get_participants(peer.clone(), 200)
    .await?;

for p in &members {
    println!(
        "{}: admin: {}, banned: {}",
        p.user.first_name.as_deref().unwrap_or("?"),
        p.is_admin(),
        p.is_banned(),
    );
}
}

Paginated iterator (large groups)

#![allow(unused)]
fn main() {
let members = client.iter_participants(peer.clone(), None, 0).await?;
for p in &members {
    println!("{}", p.user.first_name.as_deref().unwrap_or(""));
}
}

Search contacts and dialogs by name

#![allow(unused)]
fn main() {
// Returns combined results from contacts, dialogs, and global
let results: Vec<tl::enums::Peer> = client.search_peer("John").await?;
}

Participant fields

#![allow(unused)]
fn main() {
p.user          // tl::types::User: raw user data
p.is_creator()  // bool: is the channel/group creator
p.is_admin()    // bool: has any admin rights
p.is_banned()   // bool: is banned/restricted
p.is_member()   // bool: active member (not banned, not left)
}

Kick participant

#![allow(unused)]
fn main() {
// Removes the user from a basic group by chat_id (i64)
// For channels/supergroups, use ban instead
client.kick(chat_id, user_id).await?;
}

Note: kick takes a chat_id: i64, not a PeerRef. Use the raw numeric ID of the basic group.

Ban participant

ban takes a Unix timestamp for until_date. For granular per-permission restrictions use restrict with BannedRightsBuilder.

#![allow(unused)]
fn main() {
// Permanent full ban (until_date = 0)
client.ban(peer.clone(), user_id, None).await?;

// Timed ban: expires in 24 h
let expires = (std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() + 86400) as i32;
client.ban(peer.clone(), user_id, Some(expires)).await?;

// Unban: set a past timestamp (e.g. 1) to lift the ban
client.ban(peer.clone(), user_id, Some(1)).await?;
}

For per-permission restrictions (no media, no stickers, etc.) use restrict with BannedRightsBuilder:

#![allow(unused)]
fn main() {
use ferogram::participants::BannedRightsBuilder;

client
    .restrict(
        peer.clone(),
        user_input_peer,
        BannedRightsBuilder::new()
            .send_media(true)
            .send_stickers(true)
            .until_date(expires),
    )
    .await?;
}

BannedRightsBuilder methods

Promote admin: set_admin and AdminRightsBuilder

set_admin is a boolean shorthand - true grants all standard rights, false demotes:

#![allow(unused)]
fn main() {
// Quick promote (all standard rights except add_admins)
client.set_admin(peer.clone(), user_id, AdminRightsBuilder::full_admin()).await?;

// Demote back to regular member
client.set_admin(peer.clone(), user_id, AdminRightsBuilder::new()).await?;
}

For fine-grained control, use set_admin with AdminRightsBuilder:

#![allow(unused)]
fn main() {
use ferogram::participants::AdminRightsBuilder;

// Promote with specific rights and a custom title
client
    .set_admin(
        peer.clone(),
        user_id,
        AdminRightsBuilder::new()
            .post_messages(true)
            .delete_messages(true)
            .ban_users(true)
            .invite_users(true)
            .pin_messages(true)
            .rank("Moderator"), // custom admin title (max 16 chars)
    )
    .await?;

// Full admin (all standard rights except add_admins)
client
    .set_admin(peer.clone(), user_id, AdminRightsBuilder::full_admin())
    .await?;

// Demote: pass an empty builder to remove all admin rights
client
    .set_admin(peer.clone(), user_id, AdminRightsBuilder::new())
    .await?;
}

AdminRightsBuilder methods

Get participant permissions

Check the effective permissions of a user in a channel or supergroup:

#![allow(unused)]
fn main() {
use ferogram::participants::ParticipantPermissions;

let perms: ParticipantPermissions = client
    .get_permissions(peer.clone(), user_id)
    .await?;

println!("Creator: {}", perms.is_creator());
println!("Admin: {}",   perms.is_admin());
println!("Banned: {}",  perms.is_banned());
println!("Member: {}",  perms.is_member());
println!("Can send: {}", perms.can_send_messages);
println!("Can pin: {}",  perms.can_pin_messages);
println!("Admin title: {:?}", perms.admin_rank);
}

ParticipantPermissions fields & methods

Profile photos

#![allow(unused)]
fn main() {
// Fetch a page of profile photos (limit = number to fetch)
let photos = client.get_profile_photos(peer.clone(), 10).await?;

// Lazy iterator across all pages (chunk_size = 0 uses default of 100)
let mut iter = client.iter_profile_photos(peer.clone(), 0).await?;
while let Some(photo) = iter.next().await? {
    // download photo bytes...
}
}

Join and leave chats

#![allow(unused)]
fn main() {
// Join a public group or channel
client.join_chat("@somegroup").await?;

// Accept a private invite link
client.join_link("https://t.me/joinchat/AbCdEfG").await?;

// Parse invite hash from any link format
let hash = Client::parse_invite_hash("https://t.me/+AbCdEfG12345");

// Leave / remove dialog
client.delete_dialog(peer.clone()).await?;
}

ParticipantStatus enum

#![allow(unused)]
fn main() {
use ferogram::participants::ParticipantStatus;

for p in &members {
    match p.status {
        ParticipantStatus::Member     => println!("Regular member"),
        ParticipantStatus::Creator    => println!("Creator"),
        ParticipantStatus::Admin      => println!("Admin"),
        ParticipantStatus::Restricted => println!("Restricted"),
        ParticipantStatus::Banned     => println!("Banned"),
        ParticipantStatus::Left       => println!("Left"),
    }
}
}

ProfilePhotoIter: extended methods

#![allow(unused)]
fn main() {
let mut iter = client.iter_profile_photos(user_id);

// Total photo count (available after first fetch)
if let Some(total) = iter.total_count() {
    println!("{total} profile photos");
}

// Collect all photos at once
let all_photos = iter.collect().await?;
}

Low-level rights setters

For advanced use cases, restrict and set_admin give direct access to the TL layer:

#![allow(unused)]
fn main() {
// Set banned rights directly (channel/supergroup only)
client.restrict(
    peer.clone(),
    user_input_peer,
    BannedRightsBuilder::new().send_media(true),
).await?;

// Set admin rights directly
client.set_admin(
    peer.clone(),
    user_input_peer,
    AdminRightsBuilder::new().delete_messages(true),
    Some("Moderator".into()),  // optional custom rank
).await?;
}

Admin & Ban Rights

ferogram provides two fluent builders for granular admin and ban rights: AdminRightsBuilder and BannedRightsBuilder: both in the ferogram::participants module.

BannedRightsBuilder: restrict a member

#![allow(unused)]
fn main() {
use ferogram::participants::BannedRightsBuilder;

// Permanent full ban
client
    .ban(peer.clone(), user_id, None)
    .await?;

// Partial restriction (no media, expires in 24 h)
let tomorrow = (std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH).unwrap().as_secs() + 86400) as i32;

client
    .ban(
        peer.clone(), user_id,
        BannedRightsBuilder::new()
            .send_media(true)
            .send_stickers(true)
            .send_gifs(true)
            .until_date(tomorrow),
    )
    .await?;

// Unban
// Passing an empty builder restores full permissions
client
    .ban(peer.clone(), user_id, None)
    .await?;
}

Method reference

Note: Setting view_messages: true is a full ban: the member cannot read messages or remain in the group.

AdminRightsBuilder: grant admin rights

#![allow(unused)]
fn main() {
use ferogram::participants::AdminRightsBuilder;

// Custom moderator
client
    .set_admin(
        peer.clone(), user_id,
        AdminRightsBuilder::new()
            .delete_messages(true)
            .ban_users(true)
            .invite_users(true)
            .pin_messages(true)
            .rank("Moderator"),  // shown next to name
    )
    .await?;

// Full admin (all standard rights)
client
    .set_admin(peer.clone(), user_id, AdminRightsBuilder::full_admin())
    .await?;

// Demote (remove all admin rights)
client
    .set_admin(peer.clone(), user_id, AdminRightsBuilder::new())
    .await?;
}

Method reference

.add_admins(true) grants significant trust: admins with this right can promote others to full admin level.

ParticipantPermissions: read effective rights

To inspect the actual current permissions of a user in a channel:

#![allow(unused)]
fn main() {
use ferogram::participants::ParticipantPermissions;

let perms: ParticipantPermissions = client
    .get_permissions(peer.clone(), user_id)
    .await?;
}

Fields & methods

Quick patterns

#![allow(unused)]
fn main() {
// Temporarily mute: no messages for 1 hour
let in_1h = (chrono::Utc::now().timestamp() + 3600) as i32;
client.ban(peer.clone(), uid,
    BannedRightsBuilder::new().send_messages(true).until_date(in_1h)
).await?;

// Promote to channel editor
client.set_admin(peer.clone(), uid,
    AdminRightsBuilder::new()
        .post_messages(true)
        .edit_messages(true)
        .delete_messages(true)
).await?;

// Check before acting
let perms = client.get_permissions(peer.clone(), uid).await?;
if !perms.is_admin() && !perms.is_banned() {
    client.ban(peer.clone(), uid, BannedRightsBuilder::full_ban()).await?;
}
}

Dialogs & History

Fetch dialogs

#![allow(unused)]
fn main() {
// Fetch up to N dialogs (returns the most recent first)
let dialogs = client.get_dialogs(50).await?;

for d in &dialogs {
    println!("{}: {} unread: top msg: {}",
        d.title(), d.unread_count(), d.top_message());
}
}

Dialog accessors

DialogIter: lazy paginated iterator

#![allow(unused)]
fn main() {
let mut iter = client.iter_dialogs();

// Total count (available after first page is fetched)
if let Some(total) = iter.total() {
    println!("Total dialogs: {total}");
}

while let Some(dialog) = iter.next(&client).await? {
    println!("{}", dialog.title());
}
}

MessageIter: lazy message history

#![allow(unused)]
fn main() {
let mut iter = client.iter_messages(peer.clone());

// Total count of messages in this chat
if let Some(total) = iter.total() {
    println!("Total messages: {total}");
}

while let Some(msg) = iter.next(&client).await? {
    println!("[{}] {}", msg.id, msg.message);
}
}

Fetch messages directly

#![allow(unused)]
fn main() {
// Latest N messages from a peer
let messages = client.get_message_history(peer.clone(), 20).await?;

// Specific message IDs
let messages = client.get_messages(peer.clone(), &[100, 101, 102]).await?;
// Returns Vec<Option<tl::enums::Message>>: None if not found

// Pinned message
let pinned = client.get_pinned_message(peer.clone()).await?;

// Fetch the message a reply refers to by ID
let parent = client.get_messages(peer.clone(), &[reply_id]).await?.into_iter().next();
}

Scheduled messages

#![allow(unused)]
fn main() {
// List all scheduled messages
let scheduled = client.get_scheduled_messages(peer.clone()).await?;

// Send a scheduled message immediately
client.send_scheduled_now(peer.clone(), &[scheduled_id]).await?;

// Cancel a scheduled message
client.delete_scheduled_messages(peer.clone(), &[scheduled_id]).await?;
}

Dialog management

#![allow(unused)]
fn main() {
// Mark all messages as read
client.mark_read(peer.clone()).await?;

// Clear @mention badges
client.clear_mentions(peer.clone()).await?;

// Leave and remove from dialog list
client.delete_dialog(peer.clone()).await?;

// Pin / unpin a dialog
client.pin_dialog(peer.clone()).await?;
client.pin_dialog(peer.clone(), false).await?;

// Get pinned dialogs (folder_id: 0 = main, 1 = archived)
let pinned = client.get_pinned_dialogs(0).await?;

// Set manual unread flag on a dialog
client.mark_dialog_unread(peer.clone(), true).await?;

// Clear the manual unread flag
client.mark_read(peer.clone()).await?;

// Join a public group/channel
client.join_chat("@somegroup").await?;

// Accept a private invite link
client.join_link("https://t.me/joinchat/AbCdEfG").await?;

// Parse invite hash from any link format
let hash = Client::parse_invite_hash("https://t.me/+AbCdEfG12345");
}

Archive & unarchive

Move a dialog into the Telegram archive (folder 1) or back to the main list (folder 0):

#![allow(unused)]
fn main() {
// Move to archive - chat disappears from the main dialog list
client.archive("@somebot").await?;

// Move back to main list
client.archive("@somebot").await?;
}

Archived chats still receive messages; they are simply hidden from the main list and muted by default until the user opens them.

Low-level folder move

For finer control (e.g. custom folders), use move_to_folder:

#![allow(unused)]
fn main() {
// folder_id 0 = main list, 1 = archive
client.move_to_folder("@somebot", 0).await?;
}

Search

ferogram provides two fluent search builders:

• SearchBuilder: search within a single peer (client.search())
• GlobalSearchBuilder: search across all dialogs (client.search_global_builder())

Both builders return Vec<IncomingMessage> from .fetch(&client).await?.

SearchBuilder: in-chat search

#![allow(unused)]
fn main() {
use ferogram_tl_types::enums::MessagesFilter;

let results = client
    .search(peer.clone(), "rust async")  // peer: impl Into<PeerRef>
    .limit(50)
    .fetch(&client)
    .await?;

for msg in &results {
    println!("[{}] {}", msg.id, msg.message);
}
}

client.search(peer, query) accepts any impl Into<PeerRef>: a &str username, a tl::enums::Peer, or a numeric i64 ID.

All SearchBuilder methods

Filter by media type

#![allow(unused)]
fn main() {
use ferogram_tl_types::enums::MessagesFilter;

// Photos only
let photos = client
    .search(peer.clone(), "")
    .filter(MessagesFilter::InputMessagesFilterPhotos)
    .limit(30)
    .fetch(&client)
    .await?;

// Documents only
let docs = client
    .search(peer.clone(), "report")
    .filter(MessagesFilter::InputMessagesFilterDocument)
    .fetch(&client)
    .await?;

// Voice messages
let voices = client
    .search(peer.clone(), "")
    .filter(MessagesFilter::InputMessagesFilterVoice)
    .fetch(&client)
    .await?;
}

Common MessagesFilter values

Date-range search

#![allow(unused)]
fn main() {
// Messages from the last 7 days
let week_ago = (std::time::SystemTime::now()
    .duration_since(std::time::UNIX_EPOCH)
    .unwrap()
    .as_secs() - 7 * 86400) as i32;

let results = client
    .search(peer.clone(), "error")
    .min_date(week_ago)
    .limit(100)
    .fetch(&client)
    .await?;
}

Search from a specific sender

#![allow(unused)]
fn main() {
// Messages sent by yourself
let mine = client
    .search(peer.clone(), "")
    .sent_by_self()
    .fetch(&client)
    .await?;

// Messages from a specific InputPeer
let alice_peer = tl::enums::InputPeer::User(tl::types::InputPeerUser {
    user_id: alice_id,
    access_hash: alice_hash,
});

let from_alice = client
    .search(peer.clone(), "hello")
    .from_peer(alice_peer)
    .fetch(&client)
    .await?;
}

Forum topic search

#![allow(unused)]
fn main() {
let results = client
    .search(supergroup_peer.clone(), "query")
    .top_msg_id(topic_msg_id)
    .fetch(&client)
    .await?;
}

Pagination

#![allow(unused)]
fn main() {
let mut offset_id = 0;

loop {
    let page = client
        .search(peer.clone(), "keyword")
        .offset_id(offset_id)
        .limit(50)
        .fetch(&client)
        .await?;

    if page.is_empty() { break; }

    for msg in &page {
        println!("[{}] {}", msg.id, msg.message);
    }

    // Move the cursor to the oldest message in this page
    offset_id = page.iter().map(|m| m.id).min().unwrap_or(0);
}
}

GlobalSearchBuilder: search all chats

#![allow(unused)]
fn main() {
let results = client
    .search_global_builder("rust async")
    .limit(30)
    .fetch(&client)
    .await?;

for msg in &results {
    println!("[{:?}] [{}] {}", msg.peer_id, msg.id, msg.message);
}
}

All GlobalSearchBuilder methods