Telegram Provider¶

Install with: pip install roomkit[telegram] (bundles telegramify-markdown, used to render Markdown into Telegram entities).

Markdown & Rich Messages¶

The provider renders outbound Markdown into native Telegram formatting via telegramify-markdown. By default it sends text with message entities (bold, code, links, etc.); if the converter is unavailable or conversion fails, it falls back to sending the raw text unformatted.

Set rich_messages=True on TelegramConfig to opt in to Bot API 10.1 Rich Messages — native tables and headings — for text sends. Each send tries the Rich Message path first and falls back to entity formatting on any failure (and never re-sends content that already reached the chat):

from roomkit.providers.telegram.config import TelegramConfig

config = TelegramConfig(
    bot_token="...",
    rich_messages=True,   # native tables/headings (Bot API 10.1)
)

TelegramBotProvider ¶

TelegramBotProvider(config)

Bases: TelegramProvider

Send messages via the Telegram Bot API.

verify_signature ¶

verify_signature(payload, signature)

Verify a Telegram webhook secret token.

Telegram's setWebhook accepts a secret_token parameter. On each webhook request Telegram sends the token in the X-Telegram-Bot-Api-Secret-Token header. Verification is a constant-time comparison of that header value against the configured :attr:TelegramConfig.webhook_secret.

Parameters:

Name	Type	Description	Default
`payload`	`bytes`	Raw request body bytes (unused).	required
`signature`	`str`	Value of the `X-Telegram-Bot-Api-Secret-Token` header.	required

Returns:

Type	Description
`bool`	True if the token matches, False otherwise.

Raises:

Type	Description
`ValueError`	If `webhook_secret` was not provided in config.

TelegramConfig ¶

Bases: BaseModel

Telegram Bot API provider configuration.

MockTelegramProvider ¶

MockTelegramProvider()

Bases: TelegramProvider

Records sent messages for verification in tests.

parse_telegram_webhook ¶

parse_telegram_webhook(payload, channel_id)

Convert a Telegram Update payload into InboundMessages.

Telegram sends one update at a time (unless using getUpdates). Only message updates are processed; edits, channel posts, and callback queries are silently skipped.

For photo messages the largest available file_id is stored in metadata under "file_id"; callers must resolve it to a download URL via the Bot API getFile endpoint.