Module telegram 

An outbound Telegram Bot API notifier.

This module exists to replace the hand-rolled sendMessage calls which had been copied between projects, each with a different subset of the hard parts missing. It is send-only on purpose: it has no polling, no webhooks, and no update handling, because none of the consuming projects receive anything.

Formatting without escaping

Messages are built from Message::builder, which emits Telegram entities rather than parse_mode markup. Telegram’s own documentation describes entities as what a Markdown or HTML parser is converted into, so nothing is lost by skipping that step — and because no markup is ever embedded in the text, interpolated values never need escaping:

use webserver_base::telegram::{ChatId, Message, ReqwestTelegram, Telegram, TelegramSettings};

let settings = TelegramSettings::builder("123456789:AA...").build()?;
let telegram = ReqwestTelegram::new(settings, None)?;

telegram.send(
    ChatId::Id(1234),
    Message::builder()
        .text("🎨 ")
        .bold("New pattern")
        .text("\nInput: ")
        .code(untrusted_filename) // no escaping, ever
        .build(),
);

What it handles

• Length. Telegram caps text at 4096 and captions at 1024 UTF-16 code units. Oversized messages are split at natural boundaries, with entities clamped and rebased onto each piece, capped at a configurable number of chunks so an upstream bug cannot become a flood.
• Rate limits. Sends are queued per chat and paced at Telegram’s documented limits: one message per second per chat, thirty per second overall.
• Retries. A 429 is retried after the retry_after Telegram supplies, up to a ceiling; transient failures back off exponentially; permanent client errors are never retried, and misconfiguration is logged loudly.
• Secrets. The bot token is a path segment of every request URL, so it is held in a BotToken which refuses to print itself, and every reqwest error has its URL stripped before it can reach a log.

Structs

BotToken

A Telegram bot token.

Entity

A styled span of a message, positioned in UTF-16 code units.

InlineBuilder

Builds the contents of a block-level entity, such as a blockquote.

Message

A fully constructed message, ready to send.

MessageBuilder

Builds a Message from styled spans.

MockTelegram

A Telegram which records messages instead of sending them.

ReqwestTelegram

A Telegram which really talks to the Bot API over HTTP.

SendOptions

Optional per-send parameters.

SentMessage

One message captured by MockTelegram.

Style

A set of inline text styles which can be combined.

TelegramSettings

Configuration for a ReqwestTelegram.

TelegramSettingsBuilder

Builds a TelegramSettings.

Enums

ChatId

Identifies the chat a message is sent to.

EntityKind

The kind of a message entity, including any data it carries.

FileSource

Where the bytes of an uploaded photo or document come from.

Media

An attachment carried alongside a message’s caption.

TelegramError

Every way a Telegram send can fail.

Constants

DEFAULT_CONNECT_TIMEOUT

Default timeout for establishing a connection.

DEFAULT_GLOBAL_PER_SECOND

Default ceiling on messages per second across all chats.

DEFAULT_MAX_CHUNKS

Default ceiling on how many messages one oversized message may become.

DEFAULT_MAX_INPUT_BYTES

Default ceiling on the size of a single message, in bytes.

DEFAULT_MAX_RETRIES

Default number of retries for transient failures.

DEFAULT_MAX_RETRY_AFTER

Default ceiling on an honored retry_after.

DEFAULT_PER_CHAT_INTERVAL

Default minimum spacing between two messages to the same chat.

DEFAULT_QUEUE_CAPACITY

Default number of messages held per chat before new sends are dropped.

DEFAULT_REQUEST_TIMEOUT

Default timeout for a complete request.

MAX_CAPTION_LENGTH

Telegram’s maximum media caption length, in UTF-16 code units.

MAX_TEXT_LENGTH

Telegram’s maximum message text length, in UTF-16 code units.

TELEGRAM_API_BASE_URL

The official Telegram Bot API host.

Traits

Telegram

Sends outbound Telegram notifications.