Crate grammers_client 

Brief on Telegram’s API

This library is a high-level implementation to access Telegram’s API, which essentially lets you automate everything you can do with official Telegram clients and more from Rust, or even control bot accounts, making it a viable alternative to using the Telegram Bot API.

In order to create an application with the library for people to use, you will need to obtain a developer API ID first. You can embed it as a constant in your binary and ship that to users (anyone can login, including yourself and bots, with the developer API ID; they do not need to provide their own API ID).

Once that’s ready, create a new Client instance with its Client::new method and start making API calls.

Method cost

When a method is said to be “expensive”, this often means that calling it too much in a certain period of time will result in the API returning “flood wait” errors, meaning that the method cannot be called again for a certain amount of seconds (trying to do so will continue to return the flood wait error for that duration).

On the other hand, a “cheap” method can be called a lot and is unlikely to result in a flood wait error. However, all methods can potentially cause a flood wait, so some care is still required.

There is nothing wrong with causing the API to return flood wait errors, but it is something to be avoided. Because they are expected, the default ClientConfiguration will sleep on small flood errors to prevent interruption of simple scripts.

A flood wait error is different from a peer flood error. A peer flood error means the flood limitation is applied account-wide, and its duration is undefined. This often means that the account spammed, or a young account tried to contact too many peers.

Re-exports

For convenience and to ease using compatible traits in lockstep, this library re-exports several modules and types from its direct dependencies.

grammers-mtsender as sender

grammers_client is purely a friendlier abstraction on top of the SenderPool, which is responsible for abstracting the connection wholesale. The InvocationError is also re-exported at the top level, as all methods that interact with the API eventually need to invoke the request and may thus fail. You may also use the Result alias, which has the InvocationError set as its error variant.

If you need access to the rest of the crate (e.g. to configure the SenderPool), it is re-exported under sender.

grammers-session as session

After login, the generated Authorization Key should be persisted and reused, in order to avoid logging in again, as that is a very expensive method.

Session storages are responsible for doing so, and you may even implement your own by using the session::Session trait.

grammers-tl-types as tl

This crate is re-exported wholesale under the tl namespace (short for Type Language). All Telegram types and functions are automatically generated from their public schema, which is versioned by “layers”. For now and the foreseeable future, grammers will only offer one layer at a time.

When the friendly API of grammers_client falls short, you can reach out for its raw tl::types to access all the information Telegram returned on its responses. Additionally, if the Client is missing a method to do what you need, you may directly Client::invoke any of the tl::functions offered by Telegram’s API.

Using raw types is discouraged. Not only are they far clunkier to use, but they are also not part of the semantic versioning. While patch versions won’t change the layer, minor versions will, which would traditionally be considered a breaking change.

Re-exports

pub use client::Client;

pub use client::PeerSearchItem;

pub use client::SignInError;

pub use grammers_mtsender as sender;

pub use grammers_session as session;

pub use grammers_tl_types as tl;

Modules

client

Contains client-specific configuration and types.

media

Types relating to message media and downloadables.

message

Types relating to chat messages.

peer

Types relating to users, groups and channels.

update

Update types about events received from Telegram.

Structs

SenderPool

Builder to configure the runner to drive I/O and linked handles.

Enums

InvocationError

This error occurs when a Remote Procedure call was unsuccessful.

Type Aliases

Result

Alias for std::result::Result with the error set to InvocationError.