shilling
A minimal, typed Telegram Bot API client in Rust focused on long-polling, structured updates, and reliable outgoing calls.
Name
The crate is named after Pavel Lvovich Schilling (1786–1837), a Russian scientist and diplomat who built the first practical electromagnetic telegraph in 1832 — the earliest device to transmit coded messages over a wire and the conceptual ancestor of every messaging protocol that followed, Telegram included.
Features
- Long-polling via
getUpdateswith bounded timeouts and a configurable allowed-updates filter. - Strongly-typed incoming model:
Update,Message,CallbackQuery, media payloads, inline keyboards. - Strongly-typed outgoing model:
sendMessage,sendPhoto,sendVideo,sendVoice,sendAudio,sendDocument,sendAnimation,sendVideoNote,sendSticker,setMessageReaction. - Newtype IDs (
ChatId,MessageId,UserId,UpdateId,FileId,Username, …) — no stringly-typed identifiers. - Heuristic sender classification (
UserAccountType: person, bot, channel publisher, channel group, foreign channel). - Retry policy with exponential backoff, jitter, and Bot API
retry_afterhandling for transport errors, 5xx, and 429. - Per-request
reqwest::Clienttuned for HTTP keep-alive and idle-pool reuse, shared viaonce_cell. tracingspans on every Bot API call (method,chat_id, attempt, duration).- Builder-validated
Config— invalid combinations are rejected before any I/O.
Requirements
- Rust stable, edition 2024.
- Tokio multi-thread runtime.
- A Telegram bot token from @BotFather.
Configuration
The client reads credentials from the environment:
| Variable | Required | Description |
|---|---|---|
TELEGRAM_BOT_ID |
yes | Numeric bot id (the part before : in the bot token). |
TELEGRAM_BOT_TOKEN |
yes | Bot token (the part after :). |
Defaults applied by ConfigBuilder:
| Field | Default |
|---|---|
base_url |
https://api.telegram.org |
get_updates_timeout |
50 seconds (range 0..=50) |
get_updates_limit |
100 (range 1..=100) |
allowed_updates |
["message", "edited_message", "callback_query"] |
Usage
Add the crate to your Cargo.toml:
[]
= { = "https://github.com/<owner>/shilling" }
= { = "1", = ["rt-multi-thread", "macros"] }
Setting a reaction:
use set_message_reaction;
use SetMessageReactionRequest;
set_message_reaction
.await?;
Examples
Runnable examples live in examples/. All of them call
ConfigBuilder::try_credentials_from_env(), which reads the bot credentials
from the process environment.
Environment variables
| Variable | send_message |
long_polling |
Description |
|---|---|---|---|
TELEGRAM_BOT_ID |
✓ | ✓ | Numeric bot id (the part before : in the bot token). |
TELEGRAM_BOT_TOKEN |
✓ | ✓ | Bot token (the part after :). |
TELEGRAM_CHAT_ID |
✓ | Destination chat id for the outgoing message. |
Available examples
| Example | What it does | Run |
|---|---|---|
send_message |
Sends one text message to TELEGRAM_CHAT_ID. |
cargo run --example send_message |
long_polling |
Runs the run_long_polling runtime with a placeholder handler — replace its body with your own sync/async code. |
cargo run --example long_polling |
Running
# long_polling: only the two variables above are needed
# send_message: additionally requires the destination chat id
Reliability
- Every outgoing call has an explicit timeout (
10sfor send/reactions;get_updates_timeout + 5sfor long-polling). - Up to
3attempts per request. - Backoff is exponential (
200msbase, capped at5s) with up to 50% jitter. 429responses honorparameters.retry_after.4xx(HTTP or Bot API) are non-retryable and propagated to the caller.
Errors
All public client functions return Result<_, ClientError>. ClientError is exhaustive:
| Variant | When it is returned |
|---|---|
Url |
URL building failed for the method. |
Transport |
Network/transport failure after retries. |
Http |
Non-2xx HTTP outside the retry policy. |
Api |
Bot API returned ok = false (carries code and text). |
ConfigBuilder::build returns TelegramConfigError for missing credentials, malformed base URL, or out-of-range polling parameters.
Project layout
src/
client.rs long-polling, retries, request/response envelope
config.rs typed config + validating builder
ids.rs newtype IDs (string and integer)
incoming.rs Update / Message / CallbackQuery / media payloads
outgoing.rs send* request bodies and setMessageReaction
lib.rs public re-exports
Testing
Tests use rstest for parameterization and insta for snapshot assertions (config validation, payload shapes, retry-policy boundaries).
License
MIT — see LICENSE.