Configuration

Config is the struct passed to Client::connect. The recommended way to build it is via Client::builder(). All fields except api_id and api_hash have defaults.

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

let (client, _shutdown) = Client::builder()
    .api_id(12345)
    .api_hash("your_api_hash")
    .session("bot.session")       // default: "ferogram.session"
    .transport(TransportKind::Obfuscated { secret: None })
    .catch_up(false)
    .connect()
    .await?;
}

Builder methods

api_id / api_hash

Required. Get these from my.telegram.org.

#![allow(unused)]
fn main() {
.api_id(12345)
.api_hash("your_hash")
}

session

Path to a binary session file. Default: "ferogram.session".

#![allow(unused)]
fn main() {
.session("mybot.session")
}

session_string

Portable base64 session (for serverless / env-var storage). Pass an empty string to start fresh.

#![allow(unused)]
fn main() {
.session_string(std::env::var("SESSION").unwrap_or_default())
}

in_memory

Non-persistent session. Useful for tests.

#![allow(unused)]
fn main() {
.in_memory()
}

session_backend

Inject a custom SessionBackend directly, e.g. LibSqlBackend:

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

.session_backend(Arc::new(LibSqlBackend::new("remote.db")))
}

transport

Which MTProto framing to use. Default: TransportKind::Abridged.

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

// plain obfuscation, no proxy
.transport(TransportKind::Obfuscated { secret: None })

// Intermediate framing
.transport(TransportKind::Intermediate)

// FakeTLS (manual, normally set by .mtproxy())
.transport(TransportKind::FakeTls {
    secret: [0xab; 16],
    domain: "example.com".into(),
})
}

When using .mtproxy(), the transport is set automatically. Do not also call .transport().

socks5

Route connections through a SOCKS5 proxy.

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

// no auth
.socks5(Socks5Config::new("127.0.0.1:1080"))

// with auth
.socks5(Socks5Config::with_auth("proxy.example.com:1080", "user", "pass"))
}

mtproxy

Route connections through an MTProxy relay. The transport is auto-selected from the secret.

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

let proxy = parse_proxy_link("tg://proxy?server=...&port=443&secret=...").unwrap();
.mtproxy(proxy)
}

See Proxies & Transports for full details.

dc_addr

Override the initial DC address. After login the correct DC is cached in the session, so this is only needed if you know exactly which DC to target.

#![allow(unused)]
fn main() {
.dc_addr("149.154.167.51:443")  // DC2
}

catch_up

When true, replays missed updates via updates.getDifference on reconnect. Default: false.

#![allow(unused)]
fn main() {
.catch_up(true)
}

allow_ipv6

Allow IPv6 DC addresses. Default: false.

#![allow(unused)]
fn main() {
.allow_ipv6(true)
}

retry_policy

How to handle FLOOD_WAIT errors. Default: AutoSleep (sleep the required duration and retry).

#![allow(unused)]
fn main() {
use std::sync::Arc;
use ferogram::retry::{AutoSleep, NoRetries};

.retry_policy(Arc::new(AutoSleep::default()))   // sleep and retry
.retry_policy(Arc::new(NoRetries))              // propagate immediately
}

Building Config without connecting

#![allow(unused)]
fn main() {
let config = Client::builder()
    .api_id(12345)
    .api_hash("hash")
    .build()?;

// later
let (client, _shutdown) = Client::connect(config).await?;
}

build() returns Err(BuilderError::MissingApiId) or Err(BuilderError::MissingApiHash) if those fields are missing, before touching the network.