Struct grammers_client::client::client::Client

pub struct Client(/* private fields */);

A client capable of connecting to Telegram and invoking requests.

This structure is the “entry point” of the library, from which you can start using the rest.

This structure owns all the necessary connections to Telegram, and has implementations for the most basic methods, such as connecting, signing in, or processing network events.

On drop, all state is synchronized to the session. The Session must be explicitly saved to disk with Session::save_to_file for persistence

Implementations

impl Client

Method implementations related with the authentication of the user into the API.

Most requests to the API require the user to have authorized their key, stored in the session, before being able to use them.

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

Returns true if the current account is authorized. Otherwise, logging in will be required before being able to invoke requests.

This will likely be the first method you want to call on a connected Client. After you determine if the account is authorized or not, you will likely want to use either Client::bot_sign_in or Client::request_login_code.

Examples

if client.is_authorized().await? {
    println!("Client is not authorized, you will need to sign_in!");
} else {
    println!("Client already authorized and ready to use!")
}

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

Signs in to the bot account associated with this token.

This is the method you need to call to use the client under a bot account.

It is recommended to save the Client::session() on successful login, and if saving fails, it is recommended to Client::sign_out. If the session cannot be saved, then the authorization will be “lost” in the list of logged-in clients, since it is unaccessible.

Examples

// Note: this token is obviously fake.
//       Obtain your own by talking to @BotFather via a Telegram app.
const TOKEN: &str = "776609994:AAFXAy5-PawQlnYywUlZ_b_GOXgarR3ah_yq";

let user = match client.bot_sign_in(TOKEN).await {
    Ok(user) => user,
    Err(err) => {
        println!("Failed to sign in as a bot :(\n{}", err);
        return Err(err.into());
    }
};

println!("Signed in as {}!", user.first_name());

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

Requests the login code for the account associated to the given phone number via another Telegram application or SMS.

This is the method you need to call before being able to sign in to a user account. After you obtain the code and it’s inside your program (e.g. ask the user to enter it via the console’s standard input), you will need to Client::sign_in to complete the process.

Examples

// Note: this phone number is obviously fake.
//       The phone used here does NOT need to be the same as the one used by the developer
//       to obtain the API ID and hash.
const PHONE: &str = "+1 415 555 0132";

if !client.is_authorized().await? {
    // We're not logged in, so request the login code.
    client.request_login_code(PHONE).await?;
}

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

Signs in to the user account.

You must call Client::request_login_code before using this method in order to obtain necessary login token, and also have asked the user for the login code.

It is recommended to save the Client::session() on successful login, and if saving fails, it is recommended to Client::sign_out. If the session cannot be saved, then the authorization will be “lost” in the list of logged-in clients, since it is unaccessible.

Examples

 async fn f(client: grammers_client::Client) -> Result<(), Box<dyn std::error::Error>> {
fn ask_code_to_user() -> String {
    unimplemented!()
}

let token = client.request_login_code(PHONE).await?;
let code = ask_code_to_user();

let user = match client.sign_in(&token, &code).await {
    Ok(user) => user,
    Err(SignInError::PasswordRequired(_token)) => panic!("Please provide a password"),
    Err(SignInError::SignUpRequired { terms_of_service: tos }) => panic!("Sign up required"),
    Err(err) => {
        println!("Failed to sign in as a user :(\n{}", err);
        return Err(err.into());
    }
};

println!("Signed in as {}!", user.first_name());

pub async fn check_password( &self, password_token: PasswordToken, password: impl AsRef<[u8]> ) -> Result<User, SignInError>

Sign in using two-factor authentication (user password).

PasswordToken can be obtained from SignInError::PasswordRequired error after the Client::sign_in method fails.

Examples

use grammers_client::SignInError;

fn get_user_password(hint: &str) -> Vec<u8> {
    unimplemented!()
}


// ... enter phone number, request login code ...

let user = match client.sign_in(&token, &code).await {
    Err(SignInError::PasswordRequired(password_token) ) => {
        let mut password = get_user_password(password_token.hint().unwrap());

        client
            .check_password(password_token, password)
            .await.unwrap()
    }
    Ok(user) => user,
    Ok(_) => panic!("Sign in required"),
    Err(err) => {
        panic!("Failed to sign in as a user :(\n{err}");
    }
};

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

Signs out of the account authorized by this client’s session.

If the client was not logged in, this method returns false.

The client is not disconnected after signing out.

Note that after using this method you will have to sign in again. If all you want to do is disconnect, simply drop the Client instance.

Examples

if client.sign_out().await.is_ok() {
    println!("Signed out successfully!");
} else {
    println!("No user was signed in, so nothing has changed...");
}

pub fn session(&self) -> &Session

Synchronize all state to the session file and provide mutable access to it.

You can use this to temporarily access the session and save it wherever you want to.

Panics if the type parameter does not match the actual session type.

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

Calls Client::sign_out and disconnects.

The client will be disconnected even if signing out fails.

impl Client

Method implementations related to dealing with bots.

pub fn inline_query<C: Into<PackedChat>>( &self, bot: C, query: &str ) -> InlineResultIter

Perform an inline query to the specified bot.

The query text may be empty.

The return value is used like any other async iterator, by repeatedly calling next.

Executing the query will fail if the input chat does not actually represent a bot account supporting inline mode.

Examples

// This is equivalent to writing `@bot inline query` in a Telegram app.
let mut inline_results = client.inline_query(&bot, "inline query");

while let Some(result) = inline_results.next().await? {
    println!("{}", result.title().unwrap());
}

pub async fn edit_inline_message<M: Into<InputMessage>>( &self, message_id: InputBotInlineMessageId, input_message: M ) -> Result<bool, InvocationError>

impl Client

Method implementations related to dealing with chats or other users.

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

Resolves a username into the chat that owns it, if any.

Note that this method is expensive to call, and can quickly cause long flood waits.

Examples

if let Some(chat) = client.resolve_username("username").await? {
    println!("Found chat!: {:?}", chat.name());
}

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

Fetch full information about the currently logged-in user.

Although this method is cheap to call, you might want to cache the results somewhere.

Examples

println!("Displaying full user information of the logged-in user:");
dbg!(client.get_me().await?);

pub fn iter_participants<C: Into<PackedChat>>(&self, chat: C) -> ParticipantIter

Iterate over the participants of a chat.

The participants are returned in no particular order.

When used to iterate the participants of “user”, the iterator won’t produce values.

Examples

let mut participants = client.iter_participants(&chat);

while let Some(participant) = participants.next().await? {
    println!("{} has role {:?}", participant.user.first_name(), participant.role);
}

pub async fn kick_participant<C: Into<PackedChat>, U: Into<PackedChat>>( &self, chat: C, user: U ) -> Result<(), InvocationError>

Kicks the participant from the chat.

This will fail if you do not have sufficient permissions to perform said operation.

The kicked user will be able to join after being kicked (they are not permanently banned).

Kicking someone who was not in the chat prior to running this method will be able to join after as well (effectively unbanning them).

When used to kick users from “user” chat, nothing will be done.

Examples

match client.kick_participant(&chat, &user).await {
    Ok(_) => println!("user is no more >:D"),
    Err(_) => println!("Kick failed! Are you sure you're admin?"),
};

pub fn set_banned_rights<C: Into<PackedChat>, U: Into<PackedChat>>( &self, channel: C, user: U ) -> BannedRightsBuilder<impl Future<Output = Result<(), InvocationError>>>

Set the banned rights for a specific user.

Returns a new BannedRightsBuilder instance. Check out the documentation for that type to learn more about what restrictions can be applied.

Nothing is done until it is awaited, at which point it might result in error if you do not have sufficient permissions to ban the user in the input chat.

By default, the user has all rights, and you need to revoke those you want to take away from the user by setting the permissions to false. This means that not taking away any permissions will effectively unban someone, granting them all default user permissions.

By default, the ban is applied forever, but this can be changed to a shorter duration.

The default group rights are respected, despite individual restrictions.

Example

// This user keeps spamming pepe stickers, take the sticker permission away from them
let res = client
    .set_banned_rights(&chat, &user)
    .send_stickers(false)
    .await;

match res {
    Ok(_) => println!("No more sticker spam!"),
    Err(_) => println!("Ban failed! Are you sure you're admin?"),
};

pub fn set_admin_rights<C: Into<PackedChat>, U: Into<PackedChat>>( &self, channel: C, user: U ) -> AdminRightsBuilder<impl Future<Output = Result<(), InvocationError>>>

Set the administrator rights for a specific user.

Returns a new AdminRightsBuilder instance. Check out the documentation for that type to learn more about what rights can be given to administrators.

Nothing is done until it is awaited, at which point it might result in error if you do not have sufficient permissions to grant those rights to the other user.

By default, no permissions are granted, and you need to specify those you want to grant by setting the permissions to true. This means that not granting any permission will turn the user into a normal user again, and they will no longer be an administrator.

The change is applied forever and there is no way to set a specific duration. If the user should only be an administrator for a set period of time, the administrator permissions must be manually revoked at a later point in time.

Example

// Let the user pin messages and ban other people
let res = client.set_admin_rights(&chat, &user)
    .load_current()
    .await?
    .pin_messages(true)
    .ban_users(true)
    .await?;

pub fn iter_profile_photos<C: Into<PackedChat>>( &self, chat: C ) -> ProfilePhotoIter

Iterate over the history of profile photos for the given user or chat.

Note that the current photo might not be present in the history, and to avoid doing more work when it’s generally not needed (the photo history tends to be complete but in some cases it might not be), it’s up to you to fetch this photo from the full channel.

Note that you cannot use these photos to send them as messages directly. They must be downloaded first, then uploaded, and finally sent.

Examples

let mut photos = client.iter_profile_photos(&chat);

while let Some(photo) = photos.next().await? {
    println!("Did you know chat has a photo with ID {}?", photo.id());
}

pub async fn unpack_chat( &self, packed_chat: PackedChat ) -> Result<Chat, InvocationError>

Convert a PackedChat back into a Chat.

Example

let chat = client.unpack_chat(packed_chat).await?;

println!("Found chat: {}", chat.name());

pub async fn get_permissions<C: Into<PackedChat>, U: Into<PackedChat>>( &self, chat: C, user: U ) -> Result<ParticipantPermissions, InvocationError>

Get permissions of participant user from chat chat.

Panics

Panics if chat isn’t channel or chat, and if user isn’t user

pub async fn join_chat<C: Into<PackedChat>>( &self, chat: C ) -> Result<Option<Chat>, InvocationError>

Join a public group or channel.

A channel is public if it has a username. To join private chats, Client::accept_invite_link should be used instead.

impl Client

Method implementations related to open conversations.

pub fn iter_dialogs(&self) -> DialogIter

Returns a new iterator over the dialogs.

While iterating, the update state for any broadcast channel or megagroup will be set if it was unknown before. When the update state is set for these chats, the library can actively check to make sure it’s not missing any updates from them (as long as the queue limit for updates is larger than zero).

Examples

let mut dialogs = client.iter_dialogs();

while let Some(dialog) = dialogs.next().await? {
    let chat = dialog.chat();
    println!("{} ({})", chat.name(), chat.id());
}

pub async fn delete_dialog<C: Into<PackedChat>>( &self, chat: C ) -> Result<(), InvocationError>

Deletes a dialog, effectively removing it from your list of open conversations.

The dialog is only deleted for yourself.

Deleting a dialog effectively clears the message history and “kicks” you from it.

For groups and channels, this is the same as leaving said chat. This method does not delete the chat itself (the chat still exists and the other members will remain inside).

Examples

// Consider making a backup before, you will lose access to the messages in chat!
client.delete_dialog(&chat).await?;

pub async fn mark_as_read<C: Into<PackedChat>>( &self, chat: C ) -> Result<(), InvocationError>

Mark a chat as read.

If you want to get rid of all the mentions (for example, a voice note that you have not listened to yet), you need to also use Client::clear_mentions.

Examples

client.mark_as_read(&chat).await?;

pub async fn clear_mentions<C: Into<PackedChat>>( &self, chat: C ) -> Result<(), InvocationError>

Clears all pending mentions from a chat, marking them as read.

Examples

client.clear_mentions(&chat).await?;

impl Client

Method implementations related to uploading or downloading files.

pub fn iter_download(&self, downloadable: &Downloadable) -> DownloadIter

Returns a new iterator over the contents of a media document that will be downloaded.

Examples

let mut file_bytes = Vec::new();
let mut download = client.iter_download(&downloadable);

while let Some(chunk) = download.next().await? {
    file_bytes.extend(chunk);
}

// The file is now downloaded in-memory, inside `file_bytes`!

pub async fn download_media<P: AsRef<Path>>( &self, downloadable: &Downloadable, path: P ) -> Result<(), Error>

Downloads a media file into the specified path.

If the file already exists, it will be overwritten.

This is a small wrapper around Client::iter_download for the common case of wanting to save the file locally.

Examples

client.download_media(&downloadable, "/home/username/photos/holidays.jpg").await?;

pub async fn upload_stream<S: AsyncRead + Unpin>( &self, stream: &mut S, size: usize, name: String ) -> Result<Uploaded, Error>

Uploads an async stream to Telegram servers.

The file is not sent to any chat, but can be used as media when sending messages for a certain period of time (less than a day). You can use this uploaded file multiple times.

Refer to InputMessage to learn more uses for uploaded_file.

The stream size must be known beforehand. If this is not possible, you might need to process the entire async stream to determine its size, and then use the size and the downloaded buffer.

The stream size may be less or equal to the actual length of the stream, but not more. If it’s less, you may continue to read from the stream after the method returns. If it’s more, the method will fail because it does not have enough data to read.

Note that Telegram uses the file name in certain methods, for example, to make sure the file is an image when trying to use send the file as photo media, so it is important that the file name at least uses the right extension, even if the name is a dummy value. If the input file name is empty, the non-empty dummy value “a” will be used instead. Because it has no extension, you may not be able to use the file in certain methods.

Examples

use grammers_client::InputMessage;

// In-memory `Vec<u8>` buffers can be used as async streams
let size = some_vec.len();
let mut stream = std::io::Cursor::new(some_vec);
let uploaded_file = client.upload_stream(&mut stream, size, "sleep.jpg".to_string()).await?;

client.send_message(&chat, InputMessage::text("Zzz...").photo(uploaded_file)).await?;

pub async fn upload_file<P: AsRef<Path>>( &self, path: P ) -> Result<Uploaded, Error>

Uploads a local file to Telegram servers.

The file is not sent to any chat, but can be used as media when sending messages for a certain period of time (less than a day). You can use this uploaded file multiple times.

Refer to InputMessage to learn more uses for uploaded_file.

If you need more control over the uploaded data, such as performing only a partial upload or with a different name, use Client::upload_stream instead.

Examples

use grammers_client::InputMessage;

let uploaded_file = client.upload_file("/home/username/photos/holidays.jpg").await?;

client.send_message(&chat, InputMessage::text("Check this out!").photo(uploaded_file)).await?;

impl Client

Method implementations related to sending, modifying or getting messages.

pub async fn send_message<C: Into<PackedChat>, M: Into<InputMessage>>( &self, chat: C, message: M ) -> Result<Message, InvocationError>

Sends a message to the desired chat.

This method can also be used to send media such as photos, videos, documents, polls, etc.

If you want to send a local file as media, you will need to use Client::upload_file first.

Refer to InputMessage to learn more formatting options, such as using markdown or adding buttons under your message (if you’re logged in as a bot).

See also: Message::respond, Message::reply.

Examples

client.send_message(&chat, "Boring text message :-(").await?;

use grammers_client::InputMessage;

client.send_message(&chat, InputMessage::text("Sneaky message").silent(true)).await?;

pub async fn edit_message<C: Into<PackedChat>, M: Into<InputMessage>>( &self, chat: C, message_id: i32, new_message: M ) -> Result<(), InvocationError>

Edits an existing message.

Similar to Client::send_message, advanced formatting can be achieved with the options offered by InputMessage.

See also: Message::edit.

Examples

let old_message_id = 123;
client.edit_message(&chat, old_message_id, "New text message").await?;

pub async fn delete_messages<C: Into<PackedChat>>( &self, chat: C, message_ids: &[i32] ) -> Result<usize, InvocationError>

Deletes up to 100 messages in a chat.

Warning: when deleting messages from small group chats or private conversations, this method cannot validate that the provided message IDs actually belong to the input chat due to the way Telegram’s API works. Make sure to pass correct Message::id’s.

The messages are deleted for both ends.

The amount of deleted messages is returned (it might be less than the amount of input message IDs if some of them were already missing). It is not possible to find out which messages were actually deleted, but if the request succeeds, none of the specified message IDs will appear in the message history from that point on.

See also: Message::delete.

Examples

let message_ids = [123, 456, 789];

// Careful, these messages will be gone after the method succeeds!
client.delete_messages(&chat, &message_ids).await?;

pub async fn forward_messages<C: Into<PackedChat>, S: Into<PackedChat>>( &self, destination: C, message_ids: &[i32], source: S ) -> Result<Vec<Option<Message>>, InvocationError>

Forwards up to 100 messages from source into destination.

For consistency with other methods, the chat upon which this request acts comes first (destination), and then the source chat.

Returns the new forwarded messages in a list. Those messages that could not be forwarded will be None. The length of the resulting list is the same as the length of the input message IDs, and the indices from the list of IDs map to the indices in the result so you can find which messages were forwarded and which message they became.

See also: Message::forward_to.

Examples

let message_ids = [123, 456, 789];

let messages = client.forward_messages(&destination, &message_ids, &source).await?;
let fwd_count = messages.into_iter().filter(Option::is_some).count();
println!("Forwarded {} out of {} messages!", fwd_count, message_ids.len());

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

Gets the Message to which the input message is replying to.

See also: Message::get_reply.

Examples

if let Some(reply) = client.get_reply_to_message(&message).await? {
    println!("The reply said: {}", reply.text());
}

pub fn iter_messages<C: Into<PackedChat>>(&self, chat: C) -> MessageIter

Iterate over the message history of a chat, from most recent to oldest.

Examples

// Note we're setting a reasonable limit, or we'd print out ALL the messages in chat!
let mut messages = client.iter_messages(&chat).limit(100);

while let Some(message) = messages.next().await? {
    println!("{}", message.text());
}

pub fn search_messages<C: Into<PackedChat>>(&self, chat: C) -> SearchIter

Iterate over the messages that match certain search criteria.

This allows you to search by text within a chat or filter by media among other things.

Examples

// Let's print all the people who think grammers is cool.
let mut messages = client.search_messages(&chat).query("grammers is cool");

while let Some(message) = messages.next().await? {
    println!("{}", message.sender().unwrap().name());
}

pub fn search_all_messages(&self) -> GlobalSearchIter

Iterate over the messages that match certain search criteria, without being restricted to searching in a specific chat. The downside is that this global search supports less filters.

This allows you to search by text within a chat or filter by media among other things.

Examples

// Let's print all the chats were people think grammers is cool.
let mut messages = client.search_all_messages().query("grammers is cool");

while let Some(message) = messages.next().await? {
    println!("{}", message.chat().name());
}

pub async fn get_messages_by_id<C: Into<PackedChat>>( &self, chat: C, message_ids: &[i32] ) -> Result<Vec<Option<Message>>, InvocationError>

Get up to 100 messages using their ID.

Returns the new retrieved messages in a list. Those messages that could not be retrieved or do not belong to the input chat will be None. The length of the resulting list is the same as the length of the input message IDs, and the indices from the list of IDs map to the indices in the result so you can map them into the new list.

Examples

let message_ids = [123, 456, 789];

let messages = client.get_messages_by_id(&chat, &message_ids).await?;
let count = messages.into_iter().filter(Option::is_some).count();
println!("{} out of {} messages were deleted!", message_ids.len() - count, message_ids.len());

pub async fn get_pinned_message<C: Into<PackedChat>>( &self, chat: C ) -> Result<Option<Message>, InvocationError>

Get the latest pin from a chat.

Examples

if let Some(message) = client.get_pinned_message(&chat).await? {
    println!("There is a message pinned in {}: {}", chat.name(), message.text());
} else {
    println!("There are no messages pinned in {}", chat.name());
}

pub async fn pin_message<C: Into<PackedChat>>( &self, chat: C, message_id: i32 ) -> Result<(), InvocationError>

Pin a message in the chat. This will not notify any users.

Examples

let message_id = 123;
client.pin_message(&chat, message_id).await?;

pub async fn unpin_message<C: Into<PackedChat>>( &self, chat: C, message_id: i32 ) -> Result<(), InvocationError>

Unpin a message from the chat.

Examples

let message_id = 123;
client.unpin_message(&chat, message_id).await?;

pub async fn unpin_all_messages<C: Into<PackedChat>>( &self, chat: C ) -> Result<(), InvocationError>

Unpin all currently-pinned messages from the chat.

Examples

client.unpin_all_messages(&chat).await?;

impl Client

Method implementations directly related with network connectivity.

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

Creates and returns a new client instance upon successful connection to Telegram.

If the session in the configuration did not have an authorization key, a new one will be created and the session will be saved with it.

The connection will be initialized with the data from the input configuration.

Examples

use grammers_client::{Client, Config};
use grammers_session::Session;

// Note: these are example values and are not actually valid.
//       Obtain your own with the developer's phone at https://my.telegram.org.
const API_ID: i32 = 932939;
const API_HASH: &str = "514727c32270b9eb8cc16daf17e21e57";

let client = Client::connect(Config {
    session: Session::load_file_or_create("hello-world.session")?,
    api_id: API_ID,
    api_hash: API_HASH.to_string(),
    params: Default::default(),
}).await?;

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

Invoke a raw API call. This directly sends the request to Telegram’s servers.

Using function definitions corresponding to a different layer is likely to cause the responses to the request to not be understood.

Warning: this method is not part of the stability guarantees of semantic versioning. It may break during minor version changes (but not on patch version changes). Use with care.

Examples

use grammers_tl_types as tl;

dbg!(client.invoke(&tl::functions::Ping { ping_id: 0 }).await?);

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

pub async fn step(&self) -> Result<(), ReadError>

Perform a single network step.

Most commonly, you will want to use the higher-level abstraction Client::next_update instead.

Examples

loop {
    // Process network events forever until we gracefully disconnect or get an error.
    client.step().await?;
}

pub async fn run_until_disconnected(self) -> Result<(), ReadError>

Run the client by repeatedly calling Client::step until a graceful disconnection occurs, or a network error occurs. Incoming updates are ignored and simply dropped. instead.

Examples

client.run_until_disconnected().await?;

impl Client

pub async fn next_update(&self) -> Result<Option<Update>, InvocationError>

Returns the next update from the buffer where they are queued until used.

Similar using an iterator manually, this method will return Some until no more updates are available (e.g. a graceful disconnection occurred).

Examples

use grammers_client::Update;

while let Some(update) = client.next_update().await? {
    // Echo incoming messages and ignore everything else
    match update {
        Update::NewMessage(mut message) if !message.outgoing() => {
            message.respond(message.text()).await?;
        }
        _ => {}
    }
}

pub fn sync_update_state(&self)

Synchronize the updates state to the session.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.

impl PartialEq for Client

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.