telegram

# Telegram Communication Out-of-band channel to the user via a Telegram bot. Use it when the terminal isn't enough — the user has walked away, the task ran long, or a decision needs confirmation while the user is mobile. For the *when-to-use* policy (and when not to), see `~/.claude/rules/telegram-communication.md`. This skill covers the *how*. ## Tools Three scripts in `~/.local/bin`: | Script | Purpose | Blocks? | |---|---|---| | `telegram-notify` | Fire-and-forget message | No | | `telegram-ask` | Send a question, wait for reply, print reply to stdout | Yes | | `telegram-poll` | Send a multiple-choice poll, wait for the vote, print selected option(s) | Yes | All three read `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` from the environment. They're sourced from `~/.api_tokens` by mise — if you hit `... not set`, the user needs to add them there. ## telegram-notify ``` telegram-notify "Build finished — 12 tests, 0 failures." telegram-notify -s "Quiet ping" # silent (no sound) telegram-notify -m "*Bold* and _italic_" # MarkdownV2 echo "long stdout" | telegram-notify # piped input ``` Returns immediately. Exit 0 on send, 2 on config error. ## telegram-ask ``` # Default: 1-hour timeout, accept any reply answer=$(telegram-ask "Proceed with the deploy?") # Short timeout for an at-keyboard yes/no answer=$(telegram-ask -t 60 "Apply the migration now?") # Constrained reply — script re-prompts until the regex matches answer=$(telegram-ask -p '^(YES|NO)$' "Force push to main? (YES/NO)") ``` Behaviour: 1. Sends the question with `force_reply: true` so the Telegram client opens a reply thread on the user's phone. 2. Drains pending updates so old messages don't satisfy the wait. 3. Long-polls (`getUpdates`, `timeout=30`) until either a matching reply arrives or the deadline passes. While waiting, re-sends the question as a reminder at exponentially increasing intervals (default: after 5m, then 10m, 20m, ... capped by `-t`) — a missed phone notification gets more than one chance, without nagging someone who's simply away from their phone. Disable with `-r 0`. 4. On timeout: prints `TIMEOUT` to stderr, sends a "(timed out)" notice to the chat, and exits 1. 5. On config error (missing token / chat id): exits 2 with a message pointing at `~/.api_tokens`. Calling pattern from a shell script: ```bash if answer=$(telegram-ask -t 300 -p '^(YES|NO)$' "Deploy to prod?"); then case "$answer" in YES) ./deploy ;; NO) echo "Aborted by user." ;; esac else echo "No reply — aborting." >&2 exit 1 fi ``` ## Calling pattern from inside a Claude Code session `telegram-ask` blocks until the user replies, and its default `-t` is 3600s (1 hour) — longer than the Bash tool's 10-minute foreground cap. Two patterns: **Short waits (≤ ~9 min)**: pass an explicit `-t` and a Bash `timeout` that exceeds it. ``` Bash( command='telegram-ask -t 480 -p "^(YES|NO)$" "Run the destructive migration?"', timeout=500000 # ms, must be > telegram-ask -t (seconds) * 1000 ) ``` **Long waits (default 1h)**: run in the background — the harness re-invokes you when the script exits, so no polling loop is needed. ``` Bash( command='telegram-ask -p "^(YES|NO)$" "Run the destructive migration?"', run_in_background=true ) ``` Read the reply from the task output when it completes. Humans routinely take 15–60 minutes to notice a phone notification; prefer the background pattern over shrinking `-t` to fit a foreground call. If the user's reply is `YES`, proceed. Anything else (including `TIMEOUT`), do not proceed — surface the result and wait for fresh direction. ## telegram-poll ``` # Single-choice, default 1-hour timeout choice=$(telegram-poll "Which environment?" "staging" "prod" "both") # Short timeout for an at-keyboard pick choice=$(telegram-poll -t 60 "Which fix?" "revert" "hotfix" "wait") # Multiple choice — user can select more than one option choices=$(telegram-poll -M "Which suites failed?" "unit" "integration" "e2e") # Silent (no notification sound) choice=$(telegram-poll -s "Non-urgent pick" "A" "B") ``` Behaviour: 1. Sends a non-anonymous poll (`is_anonymous: false`) — required so the `poll_answer` update identifies the voter; there's no other way for the bot to attribute a vote to a reply. 2. Drains pending updates so a stale vote from an earlier poll can't satisfy the wait. 3. Long-polls (`getUpdates` with `allowed_updates=["poll_answer"]`, `timeout=30`) until a `poll_answer` for this poll's id arrives or the deadline passes. While waiting, sends a plain-text nudge ("Still waiting for your vote on: ...") at exponentially increasing intervals (default: after 5m, then 10m, 20m, ... capped by `-t`) — same backoff as `telegram-ask`. Disable with `-r 0`. 4. On answer: closes the poll (`stopPoll`) and prints the selected option text(s) to stdout, one per line — not the raw option index. 5. On timeout: prints `TIMEOUT` to stderr, closes the poll, sends a "(poll timed out)" notice to the chat, and exits 1. 6. On config error or a send failure (bad option count, question too long): exits 2 with a message. Constraints (Telegram Bot API): question ≤300 characters, each option ≤100 characters, at most 10 options. Use `telegram-poll` when the choice is genuinely a fixed set of options — it renders as tappable buttons on the user's phone, which beats typing a reply for a menu of 3-10 choices. For yes/no or free-text confirmation, `telegram-ask` is still the right tool; a two-option poll is heavier than it needs to be for a plain yes/no. Calling pattern from inside a Claude Code session — same rules as `telegram-ask`: for a short explicit `-t`, the Bash `timeout` must exceed it; for the 1-hour default, use `run_in_background=true`. ``` Bash( command='telegram-poll -t 300 "Which fix?" "revert" "hotfix" "wait"', timeout=320000 # ms, must be > telegram-poll -t (seconds) * 1000 ) ``` ## Sending multi-line output Long command output → use stdin: ```bash git diff --stat | telegram-notify ``` Telegram's `sendMessage` cap is ~4096 characters. For larger payloads, send a one-line summary via `telegram-notify` and keep the full output local — don't try to chunk it across multiple messages unless the user explicitly asks. ## Markdown gotcha `-m` uses MarkdownV2, which requires escaping `_*[]()~``>#+-=|{}.!` even inside text. If you're sending arbitrary content (a commit message, a file path), prefer the default plain-text mode or pre-escape with: ```bash escaped=$(printf '%s' "$text" | sed 's/[][\\_*()~`>#+\-=|{}.!]/\\&/g') telegram-notify -m "$escaped" ``` In practice, plain text is almost always the right default. ## Failure modes | Symptom | Cause | Fix | |---|---|---| | `TELEGRAM_BOT_TOKEN not set` | mise env not loaded, or token absent in `~/.api_tokens` | Add `export TELEGRAM_BOT_TOKEN=...` and `export TELEGRAM_CHAT_ID=...` there | | `curl: (22) ... 401` | Token revoked or wrong | Re-issue via @BotFather | | `curl: (22) ... 400` on send | Bad chat id, or bot has not been started by the user | User must `/start` the bot once | | `telegram-ask` returns immediately with stale text | Another process drained updates between drain and poll | Rare; re-run | | Reply never arrives despite user typing | User typed in a different chat than `TELEGRAM_CHAT_ID` | Verify chat id with `curl .../getUpdates` after a fresh message | | Bot in a group never sees replies | Bot **privacy mode** is on — bot only sees commands and direct mentions | In @BotFather: `/mybots` → bot → Bot Settings → Group Privacy → **Turn off**. Trade-off: bot now reads every message in the group | | Group chat id stops working with `400 chat not found` | Group was upgraded to a supergroup; chat id gained a `-100` prefix | Re-run `getUpdates` and update `TELEGRAM_CHAT_ID` in `~/.api_tokens` | | `telegram-poll` never returns despite a vote | `poll_answer` wasn't in `allowed_updates`, or the vote landed on a different, older poll | Rare — the script always scopes `allowed_updates` and filters by `poll_id`; re-run if it happens | | `telegram-poll: send failed` with a 400 | Question >300 chars, an option >100 chars, or fewer than 2 / more than 10 options | Shorten the text or the option count | ## Why these tools and not `telegram-send`? `telegram-send` (the well-known Python tool) is **send-only**. It has no receive mode, no polling, no way to wait for a reply. The interactive flow needs `getUpdates` long-polling, which these three thin curl+jq wrappers provide with no extra runtime dependencies beyond `curl` and `jq` (both already on the system). ## Rationale Telegram is the user's "I might be on my phone" channel. The three tools make the natural patterns one-line: notify (no reply needed), ask (block on a free-text reply), and poll (block on a pick among fixed options). Keep messages signal-rich and infrequent — see `telegram-communication.md` for the policy on when to send vs. stay quiet.