Skip to content

xtr_telegram_notifier

Telegram for xtr-notifier: chat messages sent, edited and answered through a bot.

Install it beside xtr-notifier and a telegram://BOT_ID:TOKEN@default?channel=CHAT_ID DSN is served by :class:TelegramTransportFactory with no wiring. Build a message's options with :class:TelegramOptions — keyboards from :mod:.reply.markup, media, an edit of an earlier message, a callback query's answer.

TelegramOptions

TelegramOptions(options: Mapping[str, object] | None = None)

Bases: MessageOptionsInterface

The options of a Telegram message, one fluent call at a time.

Each method sets a field of the bot API's request, and :meth:to_options renders them, in the order they were set, as the :class:~xtr_notifier.message.MessageOptions a message carries. What a message is — a photo, a location, an edit of an earlier message — is picked by the option set; options that each pick one cannot be combined, and the transport refuses a message that combines them.

A file to upload is read when the option is set, and kept as its name and its bytes in base64, so the message stays plain data that crosses a message bus — and a worker sending it needs no access to the file the path named.

Start from options, the bot API's fields as they are sent.

Parameters:

  • options (Mapping[str, object] | None, default: None ) –

    Fields to start from; copied, so the caller's mapping cannot change these options.

recipient_id property

recipient_id: str | None

The chat the message goes to, or None for the transport's channel.

to_options

to_options() -> MessageOptions

Render the options set so far — a copy, so later calls do not change it.

chat_id

chat_id(chat_id: str) -> Self

Send to the chat chat_id rather than the transport's channel.

message_thread_id

message_thread_id(thread_id: int) -> Self

Post in the forum topic thread_id.

parse_mode

parse_mode(mode: str) -> Self

Parse the text as mode, one of the PARSE_MODE_* constants.

disable_web_page_preview

disable_web_page_preview(disable: bool) -> Self

Show no preview of the links in the text.

disable_notification

disable_notification(disable: bool) -> Self

Deliver the message silently.

protect_content

protect_content(protect: bool) -> Self

Keep the message from being forwarded or saved.

has_spoiler

has_spoiler(spoiler: bool) -> Self

Blur the photo, video or animation until it is tapped.

photo

photo(url: str) -> Self

Send a photo, by URL or file id, with the text as its caption.

upload_photo

upload_photo(path: str) -> Self

Upload the photo at path, with the text as its caption.

reply_to

reply_to(message_id: int) -> Self

Send the message as a reply to the message message_id.

reply_markup

reply_markup(markup: AbstractTelegramReplyMarkup) -> Self

Show markup with the message: a keyboard, its removal, a forced reply.

edit

edit(message_id: int) -> Self

Edit the message message_id instead of sending one: its text, or its media.

edit_caption

edit_caption(message_id: int) -> Self

Edit the caption of the media message message_id, keeping its media.

The subject of the message is the new caption.

answer_callback_query

answer_callback_query(callback_query_id: str, show_alert: bool = False, cache_time: int = 0) -> Self

Answer the callback query callback_query_id a button sent, with the text.

Parameters:

  • callback_query_id (str) –

    The query to answer.

  • show_alert (bool, default: False ) –

    Whether the text is shown as an alert rather than a toast.

  • cache_time (int, default: 0 ) –

    How many seconds the answer may be cached; 0 or less leaves it to the bot API.

location

location(latitude: float, longitude: float) -> Self

Send a point on the map.

venue

venue(latitude: float, longitude: float, title: str, address: str) -> Self

Send a named place on the map.

document

document(url: str) -> Self

Send a file, by URL or file id, with the text as its caption.

upload_document

upload_document(path: str) -> Self

Upload the file at path, with the text as its caption.

video

video(url: str) -> Self

Send a video, by URL or file id, with the text as its caption.

upload_video

upload_video(path: str) -> Self

Upload the video at path, with the text as its caption.

audio

audio(url: str) -> Self

Send an audio file, by URL or file id, with the text as its caption.

upload_audio

upload_audio(path: str) -> Self

Upload the audio file at path, with the text as its caption.

animation

animation(url: str) -> Self

Send an animation, by URL or file id, with the text as its caption.

upload_animation

upload_animation(path: str) -> Self

Upload the animation at path, with the text as its caption.

sticker

sticker(url: str, emoji: str | None = None) -> Self

Send a sticker, by URL or file id, tied to emoji; the text is not sent.

upload_sticker

upload_sticker(path: str, emoji: str | None = None) -> Self

Upload the sticker at path, tied to emoji; the text is not sent.

contact

contact(phone_number: str, first_name: str, last_name: str | None = None, v_card: str | None = None) -> Self

Send a phone contact, with a vCard when given; the text is not sent.

TelegramTransport

TelegramTransport(token: str, channel: str | None, http_client: HttpClientInterface, event_dispatcher: EventDispatcherInterface | None = None)

Bases: AbstractTransport

Posts, edits and answers through the Telegram bot API.

The chat a message goes to is the one its options name, else the channel the transport was built with. The text is sent as MarkdownV2 unless the options pick another parse mode, escaped so that a plain sentence is accepted and markup written on purpose is kept.

A file to upload arrives as its name and base64 bytes, and is sent from memory, the fields going as a form body the HTTP client sends as multipart/form-data; without one they go as JSON. The files are closed once the request is made, whatever came of it.

To find a chat's id, message the bot from that chat and read https://api.telegram.org/bot<token>/getUpdates.

Send as the bot token to channel unless a message names its chat.

Parameters:

  • token (str) –

    The bot's token, <bot id>:<secret>; never shown.

  • channel (str | None) –

    The chat sent to when a message names none, or None.

  • http_client (HttpClientInterface) –

    What the bot API is reached through.

  • event_dispatcher (EventDispatcherInterface | None, default: None ) –

    Where the message events go; None announces nothing.

supports

supports(message: MessageInterface) -> bool

Send chat messages carrying no options or Telegram's.

TelegramTransportFactory

TelegramTransportFactory(http_client: HttpClientInterface, event_dispatcher: EventDispatcherInterface | None = None)

Bases: AbstractTransportFactory

Builds a :class:TelegramTransport from telegram://BOT_ID:TOKEN@default?channel=CHAT_ID.

The bot token is the DSN's user and password joined by : — the token as the bot API hands it out. default stands for api.telegram.org; channel is the chat sent to when a message names none; ssl=false (or the older sslmode=disable) reaches the host over plain HTTP.

create

create(dsn: Dsn) -> TelegramTransport

Build the transport dsn describes.

Raises: