xtr-telegram-notifier
Telegram for xtr-notifier — chat messages posted, edited and answered through a bot, with keyboards, media and file uploads, configured by DSN.
Why?
xtr-notifier sends chat messages through whatever provider a DSN names. This
library is the Telegram provider: installed beside it, a telegram:// DSN is served with no
wiring, and a message can carry everything the bot API offers — a keyboard, a photo, a location,
an edit of a message already sent, the answer to a button's callback.
Install
uv add xtr-telegram-notifier
It needs an HTTP client implementing xtr-http-client-contracts — usually xtr-http-client.
Quick start
from xtr_http_client import HttpClient
from xtr_notifier import Chatter, Transport
from xtr_notifier.message import ChatMessage
from xtr_notifier.transport import TransportFactoryDiscovery
discovery = TransportFactoryDiscovery(
TransportFactoryDiscovery.CHATTER_GROUP, http_client=HttpClient.create()
)
transport = Transport(discovery=discovery).from_string(
"telegram://123456:ABC-DEF@default?channel=-1001234567890"
)
await Chatter(transport).send(ChatMessage("Deploy *finished* in 42s."))
The DSN
telegram://BOT_ID:SECRET@default?channel=CHAT_ID
BOT_ID:SECRET— the bot's token, as the bot API hands it out; a DSN without it, or with half of it, is refused withMissing token.orMalformed token.default—api.telegram.org; name another host (and port) to reach a local bot API server.channel— the chat a message naming none goes to. To find a chat's id, message the bot from that chat and readhttps://api.telegram.org/bot<token>/getUpdates.ssl=false— reach the host over plain HTTP;sslmode=disableis the older spelling.
The transport's string form — what errors, events and debug:config show — is
telegram://api.telegram.org?channel=CHAT_ID: never the token.
Options
TelegramOptions builds what a message carries beyond its text, one call at a time;
to_options() renders it for the message:
from xtr_notifier.message import ChatMessage
from xtr_telegram_notifier import TelegramOptions
from xtr_telegram_notifier.reply.markup import InlineKeyboardMarkup
from xtr_telegram_notifier.reply.markup.button import InlineKeyboardButton
options = (
TelegramOptions()
.chat_id("-1001234567890")
.disable_notification(True)
.reply_markup(
InlineKeyboardMarkup().inline_keyboard(
[InlineKeyboardButton("Open").url("https://example.com/deploys/42")]
)
)
)
await chatter.send(ChatMessage("Deploy finished.", options.to_options()))
What the message is follows from the option set, and only one of these may be:
| Option | Method | The text goes in |
|---|---|---|
| none | sendMessage |
text |
photo / upload_photo |
sendPhoto |
caption |
video, audio, document, animation (and upload_*) |
sendVideo, … |
caption |
sticker / upload_sticker |
sendSticker |
not sent |
location, venue, contact |
sendLocation, sendVenue, sendContact |
not sent |
edit(message_id) |
editMessageText, or editMessageMedia with one media by URL or file id |
text, or the media's caption |
edit_caption(message_id) |
editMessageCaption |
caption |
answer_callback_query(id, show_alert, cache_time) |
answerCallbackQuery |
text |
Setting two of them raises MultipleExclusiveOptionsUsedError; editing a message's media with a
file to upload raises LogicError — the bot API takes a URL or a file id there.
The text is sent as MarkdownV2 unless parse_mode(...) picks TelegramOptions.PARSE_MODE_HTML
or PARSE_MODE_MARKDOWN. It is escaped first: the characters the bot API rejects unescaped
(., !, #, +, -, =, |, {, }, >) are escaped, while markup written on purpose —
*bold*, _italic_, `code`, ~strike~, ||spoiler||, [link](https://example.com), block quotations,
custom emojis — and characters already escaped are kept.
Keyboards: InlineKeyboardMarkup with InlineKeyboardButtons (link, login URL, callback data,
inline query, payment), ReplyKeyboardMarkup with KeyboardButtons (text, contact, location,
poll), ReplyKeyboardRemove and ForceReply.
Uploads
upload_photo(path) and its siblings keep the file's path, so a message stays plain data and
can be queued on a message bus. The transport opens each file when it sends the message, sends
the fields as a form body — which the HTTP client sends as multipart/form-data, the file named
after its path — and closes the files once the request is made, whether it succeeded or not.
A field holding an object or a list, such as a reply markup, goes in that body as JSON text, the
way the bot API reads it. A message without an upload is sent as JSON.
Errors
| Error | When |
|---|---|
IncompleteDsnError |
The DSN carries no token (Missing token.) or half of one (Malformed token.) |
UnsupportedSchemeError |
The factory was handed a DSN that is not telegram:// |
UnsupportedMessageTypeError |
The transport was handed a message that is not a ChatMessage |
MultipleExclusiveOptionsUsedError |
The options pick more than one kind of message |
LogicError |
An edit replaces a media with a file to upload |
TransportError |
Unable to post the Telegram message: <description> (code <n>). (or edit, answer callback query), or Could not reach the remote Telegram server. |
Every one of them is xtr-notifier's; TransportError is what failover moves on from.
Use in an application
Everything adding this package to an application takes — and, read backwards, what removing it undoes. It ships no bundle: the notifier's bundle finds its factory by the DSN scheme.
- Install —
uv add xtr-telegram-notifier, besidextr-notifierset up as its Use in an application says. - Recipe —
uv run xtr-recipes recipes:syncdoes the Environment step below: it writesTELEGRAM_DSNin.env. It prints the step adding the transport to<app>/config/packages/notifier.py, which a recipe cannot make for you. - Configure — add
telegram=env("TELEGRAM_DSN")tochatter_transportsin<app>/config/packages/notifier.py. - Environment —
TELEGRAM_DSN,telegram://TOKEN@default?channel=CHAT_IDwith the bot's token and the chat; read when a message is first sent. - Remove — drop the
chatter_transportsentry andTELEGRAM_DSN, thenuv remove xtr-telegram-notifier. - Check —
debug:config notifierliststelegramunderchatter_transports.
Everything else — the bundle, the channel policy, queuing through the message bus — is xtr-notifier's.
Development
uv run pytest
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run ty check
License
MIT — see LICENSE.
Metadata
Release files for xtr-telegram-notifier 6.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_telegram_notifier-6.0.1.tar.gz | 20.9 kB | With provenance | Details for xtr_telegram_notifier-6.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_telegram_notifier-6.0.1-py3-none-any.whl | Python 3 | none | any | Details for xtr_telegram_notifier-6.0.1-py3-none-any.whl |
Total release size: 49.3 kB
Release files / xtr_telegram_notifier-6.0.1.tar.gz
| Download URL | xtr_telegram_notifier-6.0.1.tar.gz |
|---|---|
| Size | 20.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
203e9a99ff8c694f64a384eb70e84704d8b853760b6e5603e11dc9450b2cdc95
|
|
BLAKE2b-256 checksum How to use checksums |
2e011f81647fc284ea164e209955d73e48a13d3c13bc70ce0e71cb00e3454781
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logRelease files / xtr_telegram_notifier-6.0.1-py3-none-any.whl
| Download URL | xtr_telegram_notifier-6.0.1-py3-none-any.whl |
|---|---|
| Size | 28.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4064961018b5112cc13f58ee7efeb3db6825fbae61b32571b3910fd5dbeea96
|
|
BLAKE2b-256 checksum How to use checksums |
dbdf15293b60caf80e8d1ae16478e7b2e4b2929d79befa0ad95ee59caf1a10d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logSecurity for xtr-telegram-notifier 6.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_telegram_notifier-6.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.