Struct Client 

pub struct Client { /* private fields */ }

The main Telegram client. Cheap to clone: internally Arc-wrapped.

Implementations

impl Client

pub async fn upload_file( &self, data: &[u8], name: &str, mime_type: &str, ) -> Result<UploadedFile, InvocationError>

Upload bytes sequentially. For big files (≥ 10 MB) prefer [upload_file_concurrent] which uses parallel workers.

pub async fn upload_file_concurrent( &self, data: Arc<Vec<u8>>, name: &str, mime_type: &str, ) -> Result<UploadedFile, InvocationError>

Upload bytes using WORKER_COUNT (4) parallel workers.

Only beneficial for big files (≥ 10 MB). Falls through to sequential for small files automatically.

pub async fn upload_stream<R: AsyncRead + Unpin>( &self, reader: &mut R, name: &str, mime_type: &str, ) -> Result<UploadedFile, InvocationError>

Upload from an AsyncRead. Reads fully into memory then uploads.

pub async fn send_file( &self, peer: Peer, media: InputMedia, caption: &str, ) -> Result<(), InvocationError>

Send a file as a document or photo to a chat.

pub async fn send_album( &self, peer: Peer, items: Vec<AlbumItem>, ) -> Result<(), InvocationError>

Send multiple files as an album.

Each AlbumItem carries its own media, caption, entities (formatting), and optional reply_to message ID.

use ferogram::media::AlbumItem;

client.send_album(peer, vec![
AlbumItem::new(photo_media).caption("First photo"),
AlbumItem::new(video_media).caption("Second photo").reply_to(Some(42)),
]).await?;

// Shorthand: legacy tuple API still works via From impl
client.send_album(peer, vec![
(photo_media, "caption".to_string()).into(),
]).await?;

pub fn iter_download(&self, location: InputFileLocation) -> DownloadIter

Create a sequential chunk download iterator.

pub async fn download_media( &self, location: InputFileLocation, ) -> Result<Vec<u8>, InvocationError>

Download all bytes of a media attachment at once (sequential).

pub async fn download_media_concurrent( &self, location: InputFileLocation, size: usize, ) -> Result<Vec<u8>, InvocationError>

Download a file using WORKER_COUNT (4) parallel workers.

size must be the exact byte size of the file (obtained from the Downloadable::size accessor, or from the document’s size field).

Returns the full file bytes in order.

pub async fn download<D: Downloadable>( &self, item: &D, ) -> Result<Vec<u8>, InvocationError>

Download any Downloadable item, automatically choosing concurrent mode for files ≥ 10 MB (/ integration).

impl Client

pub async fn get_participants( &self, peer: impl Into<PeerRef>, limit: i32, ) -> Result<Vec<Participant>, InvocationError>

Fetch all participants of a chat, group or channel.

For channels this uses channels.getParticipants; for basic groups it uses messages.getFullChat.

Returns up to limit participants; pass 0 for the default (200 for channels).

pub async fn kick_participant( &self, chat_id: i64, user_id: i64, ) -> Result<(), InvocationError>

Kick a user from a basic group (chat). For channels, use [ban_participant].

pub async fn ban_participant( &self, channel: impl Into<PeerRef>, user_id: i64, until_date: i32, ) -> Result<(), InvocationError>

Ban a user from a channel or supergroup.

Pass until_date = 0 for a permanent ban.

pub async fn promote_participant( &self, channel: impl Into<PeerRef>, user_id: i64, promote: bool, ) -> Result<(), InvocationError>

Promote (or demote) a user to admin in a channel or supergroup.

Pass promote = true to grant admin rights, false to remove them.

pub async fn get_profile_photos( &self, peer: impl Into<PeerRef>, limit: i32, ) -> Result<Vec<Photo>, InvocationError>

Iterate profile photos of a user or channel.

Returns a list of photo objects (up to limit).

pub async fn iter_profile_photos( &self, peer: impl Into<PeerRef>, chunk_size: i32, ) -> Result<ProfilePhotoIter, InvocationError>

Stream profile photos of a user lazily, one page at a time.

Returns a ProfilePhotoIter that fetches photos in pages of chunk_size and exposes them one-by-one via .next().await. Set chunk_size to 0 to use the default (100).

Only works for users: channels use messages.search with a photo filter instead.

Example

let mut iter = client.iter_profile_photos(peer, 0);
while let Some(photo) = iter.next().await? {
println!("{photo:?}");
}

pub async fn search_peer( &self, query: &str, ) -> Result<Vec<Peer>, InvocationError>

Search for a peer (user, group, or channel) by name prefix.

Searches contacts, dialogs, and globally. Returns combined results.

pub async fn send_reaction( &self, peer: impl Into<PeerRef>, message_id: i32, reaction: impl Into<InputReactions>, ) -> Result<(), InvocationError>

Send a reaction to a message.

Accepts anything that converts to [InputReactions]:

// emoji shorthand
client.send_reaction(peer, msg_id, "👍").await?;

// fluent builder
use ferogram::reactions::InputReactions;
client.send_reaction(peer, msg_id, InputReactions::custom_emoji(123).big()).await?;

// remove all reactions
client.send_reaction(peer, msg_id, InputReactions::remove()).await?;

impl Client

pub async fn set_banned_rights( &self, channel: impl Into<PeerRef>, user_id: i64, build: impl FnOnce(BannedRightsBuilder) -> BannedRightsBuilder, ) -> Result<(), InvocationError>

Apply granular ban rights to a user in a channel or supergroup.

Use BannedRightsBuilder to specify which rights to restrict.

pub async fn set_admin_rights( &self, channel: impl Into<PeerRef>, user_id: i64, build: impl FnOnce(AdminRightsBuilder) -> AdminRightsBuilder, ) -> Result<(), InvocationError>

Apply granular admin rights to a user in a channel or supergroup.

Use AdminRightsBuilder to specify which rights to grant.

pub async fn iter_participants( &self, peer: impl Into<PeerRef>, filter: Option<ChannelParticipantsFilter>, limit: i32, ) -> Result<Vec<Participant>, InvocationError>

Fetch participants with an optional filter, paginated.

filter defaults to ChannelParticipantsRecent when None.

pub async fn get_permissions( &self, channel: impl Into<PeerRef>, user_id: i64, ) -> Result<ParticipantPermissions, InvocationError>

Get the effective permissions of a specific user in a channel.

impl Client

pub async fn get_difference(&self) -> Result<Vec<Update>, InvocationError>

Fetch and replay any updates missed since the persisted pts.

loops on Difference::Slice (partial response) until the server returns a final Difference or Empty never dropping a partial batch. Previous code returned after one slice, silently losing all updates in subsequent slices.

pub async fn get_channel_difference( &self, channel_id: i64, ) -> Result<Vec<Update>, InvocationError>

Fetch missed updates for a single channel.

pub async fn sync_pts_state(&self) -> Result<(), InvocationError>

pub async fn check_and_fill_gap( &self, new_pts: i32, pts_count: i32, upd: Option<Update>, ) -> Result<Vec<Update>, InvocationError>

Check global pts, buffer during possible-gap window, fetch diff if real gap.

When a global getDifference is already in-flight (getting_global_diff == true), updates are force-dispatched immediately without pts tracking. This prevents the cascade freeze that buffering caused:

1. getDiff runs; flight-buffered updates pile up in possible_gap.
2. getDiff returns; gap_tick sees has_global()=true → another getDiff.
3. Each getDiff spawns another → bot freezes under a burst of messages.

pub async fn check_and_fill_qts_gap( &self, new_qts: i32, qts_count: i32, ) -> Result<Vec<Update>, InvocationError>

Check qts (secret chat updates) and fill gap if needed.

pub async fn check_and_fill_seq_gap( &self, new_seq: i32, seq_start: i32, ) -> Result<Vec<Update>, InvocationError>

Check top-level seq and fill gap if needed.

pub async fn check_and_fill_channel_gap( &self, channel_id: i64, new_pts: i32, pts_count: i32, upd: Option<Update>, ) -> Result<Vec<Update>, InvocationError>

Check a per-channel pts, fetch getChannelDifference if there is a gap.

pub async fn check_update_deadline(&self) -> Result<(), InvocationError>

Called periodically (e.g. from keepalive) to fire getDifference if no update has been received for > 15 minutes.

also drives per-entry possible-gap deadlines independently of incoming updates. Previously the POSSIBLE_GAP_DEADLINE_MS window was only evaluated when a new incoming update called check_and_fill_gap meaning a quiet channel with a real gap would never fire getDifference until another update arrived. This which scans all LiveEntry.effective_deadline() on every keepalive tick.

impl Client

pub fn iter_inline_queries(&self) -> InlineQueryIter

Return an iterator that yields every incoming inline query (bot side).

pub async fn inline_query( &self, bot: Peer, query: &str, ) -> Result<InlineResultIter, InvocationError>

Query a bot’s inline mode and return a paginated InlineResultIter.

Equivalent to typing @bot_username query in a Telegram app.

Example

let mut iter = client.inline_query(bot, "hello").await?;
while let Some(r) = iter.next().await? {
println!("{}", r.title().unwrap_or("(no title)"));
}

impl Client

pub async fn typing( &self, peer: impl Into<PeerRef>, ) -> Result<TypingGuard, InvocationError>

Start a scoped typing indicator that auto-cancels when dropped.

A convenience wrapper around TypingGuard::start.

pub async fn typing_in_topic( &self, peer: impl Into<PeerRef>, topic_id: i32, ) -> Result<TypingGuard, InvocationError>

Start a scoped typing indicator in a forum topic thread.

topic_id is the top_msg_id of the forum topic.

pub async fn uploading_document( &self, peer: impl Into<PeerRef>, ) -> Result<TypingGuard, InvocationError>

Start a scoped “uploading document” action that auto-cancels when dropped.

pub async fn recording_video( &self, peer: impl Into<PeerRef>, ) -> Result<TypingGuard, InvocationError>

Start a scoped “recording video” action that auto-cancels when dropped.

impl Client

pub fn builder() -> ClientBuilder

Return a fluent ClientBuilder for constructing and connecting a client.

Example

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

pub async fn connect( config: Config, ) -> Result<(Self, ShutdownToken), InvocationError>

pub async fn save_session(&self) -> Result<(), InvocationError>

Persist the current session to the configured SessionBackend.

pub async fn export_session_string(&self) -> Result<String, InvocationError>

Export the current session as a portable URL-safe base64 string.

The returned string encodes the auth key, DC, update state, and peer cache. Store it in an environment variable or secret manager and pass it back via Config::with_string_session to restore the session without re-authenticating.

pub async fn media_dc_addr(&self, dc_id: i32) -> Option<String>

Return the media-only DC address for the given DC id, if known.

Media DCs (media_only = true in DcOption) are preferred for file uploads and downloads because they are not subject to the API rate limits applied to the main DC connection.

pub async fn best_media_dc_addr(&self) -> Option<(i32, String)>

Return the best media DC address for the current home DC (falls back to any known media DC if no home-DC media entry exists).

pub async fn is_authorized(&self) -> Result<bool, InvocationError>

Returns true if the client is already authorized.

pub async fn bot_sign_in(&self, token: &str) -> Result<String, InvocationError>

Sign in as a bot.

pub async fn request_login_code( &self, phone: &str, ) -> Result<LoginToken, InvocationError>

Request a login code for a user account.

pub async fn sign_in( &self, token: &LoginToken, code: &str, ) -> Result<String, SignInError>

Complete sign-in with the code sent to the phone.

pub async fn check_password( &self, token: PasswordToken, password: impl AsRef<[u8]>, ) -> Result<String, InvocationError>

Complete 2FA login.

pub async fn sign_out(&self) -> Result<bool, InvocationError>

Sign out and invalidate the current session.

pub async fn get_users_by_id( &self, ids: &[i64], ) -> Result<Vec<Option<User>>, InvocationError>

Fetch user info by ID. Returns None for each ID that is not found.

Used internally by update::IncomingMessage::sender_user.

pub async fn get_me(&self) -> Result<User, InvocationError>

Fetch information about the logged-in user.

pub fn stream_updates(&self) -> UpdateStream

Return an UpdateStream that yields incoming Updates.

The reader task (started inside connect()) sends all updates to inner.update_tx. This method proxies those updates into a fresh caller-owned channel: typically called once per bot/app loop.

pub fn signal_network_restored(&self)

Signal that network connectivity has been restored.

Call this from platform network-change callbacks: Android’s ConnectivityManager, iOS NWPathMonitor, or any other OS hook to make the client attempt an immediate reconnect instead of waiting for the exponential backoff timer to expire.

Safe to call at any time: if the connection is healthy the hint is silently ignored by the reader task; if it is in a backoff loop it wakes up and tries again right away.

pub async fn send_message( &self, peer: &str, text: &str, ) -> Result<IncomingMessage, InvocationError>

Send a text message. Use "me" for Saved Messages.

pub async fn send_message_to_peer( &self, peer: impl Into<PeerRef>, text: &str, ) -> Result<IncomingMessage, InvocationError>

Send a message to a peer (plain text shorthand).

Accepts anything that converts to PeerRef: a &str username, an i64 ID, or an already-resolved tl::enums::Peer.

pub async fn send_message_to_peer_ex( &self, peer: impl Into<PeerRef>, msg: &InputMessage, ) -> Result<IncomingMessage, InvocationError>

Send a message with full InputMessage options.

Accepts anything that converts to PeerRef. Returns the sent message as an update::IncomingMessage.

pub async fn send_to_self( &self, text: &str, ) -> Result<IncomingMessage, InvocationError>

Send directly to Saved Messages.

pub async fn edit_message( &self, peer: impl Into<PeerRef>, message_id: i32, new_text: &str, ) -> Result<(), InvocationError>

Edit an existing message.

pub async fn forward_messages( &self, destination: impl Into<PeerRef>, message_ids: &[i32], source: impl Into<PeerRef>, ) -> Result<(), InvocationError>

Forward messages from source to destination.

pub async fn forward_messages_returning( &self, destination: impl Into<PeerRef>, message_ids: &[i32], source: impl Into<PeerRef>, ) -> Result<Vec<IncomingMessage>, InvocationError>

Forward messages and return the forwarded copies.

Like [forward_messages] but parses the Updates response and returns the new messages in the destination chat, matching behaviour.

pub async fn delete_messages( &self, message_ids: Vec<i32>, revoke: bool, ) -> Result<(), InvocationError>

Delete messages by ID.

pub async fn get_messages_by_id( &self, peer: impl Into<PeerRef>, ids: &[i32], ) -> Result<Vec<IncomingMessage>, InvocationError>

Get messages by their IDs from a peer.

pub async fn get_pinned_message( &self, peer: impl Into<PeerRef>, ) -> Result<Option<IncomingMessage>, InvocationError>

Get the pinned message in a chat.

pub async fn pin_message( &self, peer: impl Into<PeerRef>, message_id: i32, silent: bool, unpin: bool, pm_oneside: bool, ) -> Result<(), InvocationError>

Pin a message in a chat.

pub async fn unpin_message( &self, peer: impl Into<PeerRef>, message_id: i32, ) -> Result<(), InvocationError>

Unpin a specific message.

pub async fn get_reply_to_message( &self, message: &IncomingMessage, ) -> Result<Option<IncomingMessage>, InvocationError>

Fetch the message that message is replying to.

Returns None if the message is not a reply, or if the original message could not be found (deleted / inaccessible).

Example

if let Some(replied) = client.get_reply_to_message(&msg).await? {
println!("Replied to: {:?}", replied.text());
}

pub async fn unpin_all_messages( &self, peer: impl Into<PeerRef>, ) -> Result<(), InvocationError>

Unpin all messages in a chat.

pub async fn search_messages( &self, peer: impl Into<PeerRef>, query: &str, limit: i32, ) -> Result<Vec<IncomingMessage>, InvocationError>

Search messages in a chat (simple form). For advanced filtering use Client::search -> SearchBuilder.

pub fn search(&self, peer: impl Into<PeerRef>, query: &str) -> SearchBuilder

Fluent search builder for in-chat message search.

pub async fn search_global( &self, query: &str, limit: i32, ) -> Result<Vec<IncomingMessage>, InvocationError>

Search globally (simple form). For filtering use Client::search_global_builder.

pub fn search_global_builder(&self, query: &str) -> GlobalSearchBuilder

Fluent builder for global cross-chat search.

pub async fn get_scheduled_messages( &self, peer: impl Into<PeerRef>, ) -> Result<Vec<IncomingMessage>, InvocationError>

Retrieve all scheduled messages in a chat.

Scheduled messages are messages set to be sent at a future time using InputMessage::schedule_date. Returns them newest-first.

Example

let scheduled = client.get_scheduled_messages(peer).await?;
for msg in &scheduled {
println!("Scheduled: {:?} at {:?}", msg.text(), msg.date());
}

pub async fn delete_scheduled_messages( &self, peer: impl Into<PeerRef>, ids: Vec<i32>, ) -> Result<(), InvocationError>

Delete one or more scheduled messages by their IDs.

pub async fn edit_inline_message( &self, id: InputBotInlineMessageId, new_text: &str, reply_markup: Option<ReplyMarkup>, ) -> Result<bool, InvocationError>

Edit an inline message by its [InputBotInlineMessageId].

Inline messages live on the bot’s home DC, not necessarily the current connection’s DC. This method sends the edit RPC on the correct DC by using the DC ID encoded in msg_id (high 20 bits of the dc_id field).

Example

client.edit_inline_message(id, "new text", None).await?;

pub async fn answer_callback_query( &self, query_id: i64, text: Option<&str>, alert: bool, ) -> Result<bool, InvocationError>

Answer a callback query from an inline keyboard button press (bots only).

pub async fn answer_inline_query( &self, query_id: i64, results: Vec<InputBotInlineResult>, cache_time: i32, is_personal: bool, next_offset: Option<String>, ) -> Result<bool, InvocationError>

pub async fn get_dialogs( &self, limit: i32, ) -> Result<Vec<Dialog>, InvocationError>

Fetch up to limit dialogs, most recent first. Populates entity/message.

pub async fn download_media_to_file( &self, location: InputFileLocation, path: impl AsRef<Path>, ) -> Result<(), InvocationError>

Download all bytes of a media attachment and save them to path.

Example

if let Some(loc) = msg.download_location() {
client.download_media_to_file(loc, "/tmp/file.jpg").await?;
}

pub async fn delete_dialog( &self, peer: impl Into<PeerRef>, ) -> Result<(), InvocationError>

pub async fn mark_as_read( &self, peer: impl Into<PeerRef>, ) -> Result<(), InvocationError>

Mark all messages in a chat as read.

pub async fn clear_mentions( &self, peer: impl Into<PeerRef>, ) -> Result<(), InvocationError>

Clear unread mention markers.

pub async fn send_chat_action( &self, peer: impl Into<PeerRef>, action: SendMessageAction, ) -> Result<(), InvocationError>

Send a chat action (typing indicator, uploading photo, etc).

For “typing” use tl::enums::SendMessageAction::Typing. For forum topic support use send_chat_action_ex or the typing_in_topic helper.

pub async fn join_chat( &self, peer: impl Into<PeerRef>, ) -> Result<(), InvocationError>

Join a public chat or channel by username/peer.

pub async fn accept_invite_link( &self, link: &str, ) -> Result<(), InvocationError>

Accept and join via an invite link.

pub fn parse_invite_hash(link: &str) -> Option<&str>

Extract hash from https://t.me/+HASH or https://t.me/joinchat/HASH.

pub async fn get_messages( &self, peer: InputPeer, limit: i32, offset_id: i32, ) -> Result<Vec<IncomingMessage>, InvocationError>

Fetch a page of messages from a peer’s history.

pub async fn resolve_peer(&self, peer: &str) -> Result<Peer, InvocationError>

Resolve a peer string to a tl::enums::Peer.

pub async fn resolve_username( &self, username: &str, ) -> Result<Peer, InvocationError>

Resolve a Telegram username to a tl::enums::Peer and cache the access hash.

Also accepts usernames without the leading @.

pub async fn invoke<R: RemoteCall>( &self, req: &R, ) -> Result<R::Return, InvocationError>

pub fn disconnect(&self)

Gracefully shut down the client.

Signals the reader task to exit cleanly. Same as cancelling the ShutdownToken returned from Client::connect.

In-flight RPCs will receive a Dropped error. Call save_session() before this if you want to persist the current auth state.

pub async fn sync_update_state(&self)

Sync the internal pts/qts/seq/date state with the Telegram server.

Called automatically on connect(). Call it manually if you need to reset the update gap-detection counters, e.g. after resuming from a long hibernation.

pub async fn count_channels(&self) -> Result<usize, InvocationError>

pub fn iter_dialogs(&self) -> DialogIter

Returns a DialogIter that can be advanced with DialogIter::next. Lets you page through all dialogs without loading them all at once.

Example

let mut iter = client.iter_dialogs();
while let Some(dialog) = iter.next(&client).await? {
println!("{}", dialog.title());
}

pub fn iter_messages(&self, peer: impl Into<PeerRef>) -> MessageIter

Fetch messages from a peer, page by page.

Returns a MessageIter that can be advanced with MessageIter::next.

Example

let mut iter = client.iter_messages(peer);
while let Some(msg) = iter.next(&client).await? {
println!("{:?}", msg.text());
}

pub async fn resolve_to_input_peer( &self, peer: &Peer, ) -> Result<InputPeer, InvocationError>

Try to resolve a peer to InputPeer, returning an error if the access_hash is unknown (i.e. the peer has not been seen in any prior API call).

pub async fn invoke_on_dc<R: RemoteCall>( &self, dc_id: i32, req: &R, ) -> Result<R::Return, InvocationError>

Invoke a request on a specific DC, using the pool.

If the target DC has no auth key yet, one is acquired via DH and then authorized via auth.exportAuthorization / auth.importAuthorization so the worker DC can serve user-account requests too.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.