Skip to main content

Crate vaegram

Crate vaegram 

Source
Expand description

A Telegram MTProto client for users and bots, written from scratch: it talks to Telegram’s main API directly, as a user account or as a bot (an alternative to the Bot API), with its own transport, auth key exchange and encrypted session, generated types for the whole API layer, and a friendly API of methods, handlers and filters on top.

use vaegram::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let app = Client::builder("my_bot", 12345, "0123456789abcdef0123456789abcdef")
        .bot_token("123456:ABC-DEF")
        .start()
        .await?;

    app.on_message(filters::command("start") & filters::private(), |msg| async move {
        msg.answer("Hello from vaegram!").await?;
        Ok(())
    });

    app.run().await
}

The api_id and api_hash come from https://my.telegram.org. Without .bot_token(..), start asks on stdin for a phone number, the login code and the two-step verification password. The first run writes my_bot.session, and later runs log in from it: see ClientBuilder for other storage and settings. Anything without a friendly method can be called with Client::invoke and the TL types in raw. The prelude brings in the client, filters, and the types and enums most bots use, with one use.

§Cargo features

None is on by default.

  • json: ToJson for every TL type and function, and JSON for raw updates and recordings.
  • unstable-raw: the TL objects behind raw updates (RawUpdate::raw(), raw_users(), raw_chats()), Incoming::into_updates() and UploadedFile::into_raw(), and the session plumbing below Client (connection::Connection, session::{Session, UpdatesRx, Incoming, Events}). Experimental: may change or go away in any release.
  • Storage engines: sqlite (SqliteStorage), redb (RedbStorage), redis (RedisStorage), mongodb (MongoStorage), postgres (PostgresStorage), s3 (S3Storage, an S3-compatible object store) and vault (VaultStorage, the login in HashiCorp Vault).
  • Observability: metrics and opentelemetry, request observers in the observe module.
  • regex: filters::regex and filters::matches.
  • Transports over TLS: websocket (ClientBuilder::websocket), dns-config (ClientBuilder::dns_fallback to Telegram’s DNS config) and web-proxy (Proxy::Web, an MTProxy behind an HTTPS relay).

Re-exports§

pub use client::Client;
pub use client::ClientBuilder;
pub use errors::Error;
pub use errors::Result;
pub use errors::RpcError;

Modules§

client
Client and its ClientBuilder.
connection
The transport under a session: framing, obfuscation, proxies, and the connection settings in Options. The connection itself is experimental and needs the unstable-raw feature:
enums
Enumerations of the friendly API, such as chat types, parse modes and client events.
errors
Error, the error every call can fail with, and Telegram’s own RpcError.
filters
Filters that choose which updates a handler gets; combine them with &, | and !.
handlers
Handler registration: groups, stopping propagation and removing a handler.
methods
The friendly API methods, all on Client, and the request builders some of them return.
observe
Watching requests: tagged marks the requests a caller causes, so an observer can tell them apart, and ready-made observers to pass to ClientBuilder::observer.
prelude
The items most bots and user clients use, to bring in with use vaegram::prelude::*;: Client and ClientBuilder, Result and Error, the filters module and Filter, the update types (Message, CallbackQuery, InlineQuery), Text and ParseMode, peers (PeerRef, User, Chat, ChatType), InputMedia, ReplyParameters and the keyboards. Result keeps a second parameter for the error, so Result<T, E> still works with it in scope. Names you import explicitly win over the glob, so use std::error::Error; or use anyhow::Result; next to it still means that item.
raw
Every type and function of Telegram’s API, generated from the TL schema, for Client::invoke.
session
The encrypted MTProto session: requests, retries, rate limits, observers and replaying recordings. The session itself is experimental and needs the unstable-raw feature:
storage
Where a client keeps its login, update state and known peers, session strings and recordings.
types
The friendly types: messages, users, chats, media, keyboards and the rest.
utils
Bot-API-style chat id conversions, and decoders for the compact thumbnails Telegram inlines.