Send Telegram alerts and run approval flows from workflows

Telegram Workflow Messaging connects shell tasks to Telegram through a bundled script using bash, curl, and jq. It supports updates, alerts, file delivery, incoming replies, and questions with selectable options that wait for an answer. Intended uses include workflow hooks, cron jobs, CI pipelines, and notifications from long-running tasks.

Commands support silent delivery, MarkdownV2 formatting with plain-text fallback, named bot accounts, and named destinations. File handling sends documents and can detect photos. The ask command returns an answer on success and a distinct timeout exit status, allowing the calling script to distinguish an answered question from no response.

Use it when the user has explicitly authorized the bot, target chat, and exact content or file. That authorization also applies before setup, reading replies, or enabling hooks. Workspace, customer, credential, and secret data must not be sent automatically. Telegram is an external service whose retention policies apply to transmitted material.

The script is not a secure production approval system by itself. Production callers must bind a response to the exact action, artifact, and destination, then check identity, freshness, and the selected option. A timeout or error is never consent. Uncertain sends are not automatically retried.

Inputs include approved message text or files, bot and destination choices, and optional question choices and timeouts. One supplied silent-message example is:

bash scripts/telegram.sh send "low priority" --silent                # no notification sound

Environment variables take precedence over a protected mode-600 configuration file. Bot tokens remain in a secret store and are not echoed, committed, or placed in shell history. The script supplies token-bearing API URLs to curl through standard input rather than process arguments.

Replies are accepted only from configured chats. Private-chat replies must come from the matching user. Group questions fail closed unless default or target-specific approver IDs explicitly identify permitted senders. Text answers must reply directly to the question; an unrelated message from an allowed sender does not count.

Setup discovers the latest pending chat, so its numeric identity requires independent verification before a confirmation send. Only one process per bot is supported because ask and read consume the same update stream. Webhook mode conflicts with getUpdates. Local configuration and cursors require a private owned directory and exclusive access.

Examples connect the script to shell automation and Claude Code notification and stop hooks. Delivery still needs inspection: text splitting can damage Unicode or markup, captions and photos have separate limits, and GIF or WebP files may require document mode for fidelity. Partial delivery, truncation, and formatting fallback must be reported truthfully.