com.blockether.vis.ext.channel-telegram.api — com.blockether/vis-channel-telegram 0.1.1

Thin wrapper around the Telegram Bot API using babashka/http-client.

Telegram Bot API reference: https://core.telegram.org/bots/api

Telegram-facing primitives:

• get-updates long-poll for incoming messages
• send-message! send text back (auto-splits at Telegram's limit)
• send-chat-action! show 'typing...' while the LLM works
• set-my-commands! install the slash-command menu shown by Telegram

answer-callback-query! clj

(answer-callback-query! token callback-query-id)

(answer-callback-query! token callback-query-id text)

Acknowledge a Telegram inline-keyboard callback. Best-effort.

delete-message! clj

(delete-message! token chat-id message-id)

Delete a message. Best-effort — swallows errors.

download-file! clj

(download-file! token file-path dest-file)

Download Telegram file file-path into dest-file. Returns dest-file.

edit-message! clj

(edit-message! token chat-id message-id text)

(edit-message! token chat-id message-id text {:keys [reply-markup plain?]})

Edit a previously-sent text message. Returns the parsed Telegram response map; caller checks :ok.

text is expected to be pre-rendered Telegram-HTML (default) or plain text when :plain? is true. :reply-markup keeps / changes the inline keyboard; pass {:inline_keyboard []} to drop it.

On HTTP 400 with description message is not modified, returns the response without retry (caller swallows). On HTTP 429, the response carries :parameters {:retry_after N} for caller backoff.

get-file clj

(get-file token file-id)

Return Telegram File metadata for file-id, including :file_path.

get-updates clj

(get-updates token offset timeout)

Long-poll Telegram for new updates.

offset - lowest update_id we haven't processed (0 on first call). timeout - seconds Telegram may hold the connection (up to 50). The HTTP client timeout is bumped by 10s to cover network slack.

Returns a vector of update maps (Telegram's Update objects).

post-message! clj

(post-message! token chat-id text)

(post-message! token chat-id text {:keys [reply-markup plain?]})

Post a single message and return the parsed Telegram response (:ok :result :description ...).

Does NOT chunk over 4096 chars — callers that need chunking go through send-message!.

text defaults to Telegram-HTML; pass :plain? true for raw.

send-audio! clj

(send-audio! token chat-id audio-file)

Send an audio file to Telegram as a generic audio attachment.

send-chat-action! clj

(send-chat-action! token chat-id action)

Show a transient indicator in the chat (e.g. 'typing...'). Best-effort: errors are swallowed because it's UX decoration, not correctness.

send-document! clj

(send-document! token chat-id doc-file filename)

(send-document! token chat-id doc-file filename caption)

Upload doc-file to Telegram as a generic document attachment.

filename names the file the recipient downloads (Telegram uses it verbatim). caption is optional chat text shown under the document.

send-message! clj

(send-message! token chat-id text)

(send-message! token chat-id text {:keys [reply-markup plain?]})

Send a text reply.

The text arg is now expected to be either:

• pre-rendered Telegram-HTML (default) — send with parse_mode=HTML;
• plain text when :plain? opt is true — send without parse_mode.

Caller is responsible for rendering. Channel registers a :channel/messages-renderer-fn that bot.clj calls before this fn. Auto-splits at 4096 chars. Falls back to plain text if Telegram rejects the HTML payload (defect-#10 last-resort safety net).

opts supports:

• :reply-markup - Telegram reply_markup map, e.g. inline keyboard;
• :plain? - skip parse_mode; ship text raw.

send-voice! clj

(send-voice! token chat-id voice-file)

Send an OGG/Opus voice-note file to Telegram.

set-my-commands! clj

(set-my-commands! token commands)

Install Telegram's slash-command menu for the bot.

commands is a seq of Telegram BotCommand maps with string keys command and description. Throws when Telegram rejects the menu so caller can log diagnostics.