Telegram

What it does

When your agent uses it

• Send a message to a Telegram user/group/channel
• Reply to a specific Telegram message with replytomessageid
• Edit an existing Telegram message
• Push proactive Telegram notifications

Example prompts

• “/telegram”

Requirements

• Python 3
• A credential in BUB_TELEGRAM_TOKEN

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

1. 1If handling a direct user message in Telegram and message_id is known, send a reply message (--reply-to).
2. 2If source metadata says sender is a bot (sender_is_bot=true), do not use reply mode, but send a normal message and prefix content with @…
3. 3For long-running tasks, optionally send one progress message, then edit that same message for final status.
4. 4ALWAYS pass message content via stdin using heredoc pipe and --message - (or --text -). NEVER embed message text directly in shell…
5. 5Prefer telegram_rich.py (rich-html-style) over telegram_send.py for anything beyond a single short paragraph. See the "Rich Messages"…

What it can do on your machine

Read from SKILL.md and the folder at commit b4a61bf. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 3 files in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • uv

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • core.telegram.org

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names these keys or tokens, usually read from environment variables:

  • BUB_TELEGRAM_TOKEN

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Telegram loads about 2.2k tokens when it runs. Until then it costs about 125 tokens; SKILL.md has 825 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~125

When it runs · the whole SKILL.md, loaded when a task matches

~2.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from bubbuild/bub at commit b4a61bf, republished under its Apache-2.0 licence (© bubbuild). 825 words, ~2,234 tokens.

name

telegram

description

Telegram Bot skill for sending and editing Telegram messages via Bot API. Use when Bub needs to: (1) Send a message to a Telegram user/group/channel, (2) Reply to a specific Telegram message with reply_to_message_id, (3) Edit an existing Telegram message, or (4) Push proactive Telegram notifications. Prefer rich formatted messages (headings, lists, tables, blockquotes, math, collapsible details, captioned media) over plain markdown whenever the content is more than one short paragraph.

metadata.channel

telegram

# Send rich message (HTML)
uv run ./scripts/telegram_rich.py \
  --chat-id <CHAT_ID> \
  --html "<h2>Title</h2><p>Body with <b>bold</b> and <code>code</code>.</p>"

# Send rich message (HTML from heredoc via file)
uv run ./scripts/telegram_rich.py \
  --chat-id <CHAT_ID> \
  --html-file /tmp/payload.html \
  --reply-to <MESSAGE_ID>

# Send rich message (Markdown instead of HTML)
uv run ./scripts/telegram_rich.py \
  --chat-id <CHAT_ID> \
  --markdown "## Title\n\n- item one\n- item two"

# Edit an existing message to become a rich message
uv run ./scripts/telegram_rich.py \
  --chat-id <CHAT_ID> \
  --edit <MESSAGE_ID> \
  --html "<p>Updated content.</p>"

# Send message (ALWAYS use heredoc stdin, never inline text in arguments)
cat << 'EOF' | uv run ${SKILL_DIR}/scripts/telegram_send.py --chat-id <CHAT_ID> --token "$BUB_TELEGRAM_TOKEN" --message -
Your message content here.
Special characters are safe: $100, "quotes", 'apostrophes', !exclamation
EOF

# Reply to a specific message
cat << 'EOF' | uv run ${SKILL_DIR}/scripts/telegram_send.py --chat-id <CHAT_ID> --token "$BUB_TELEGRAM_TOKEN" --reply-to <MESSAGE_ID> --message -
Reply content here.
EOF

# Source message sender is bot: no direct reply, use @username style
cat << 'EOF' | uv run ${SKILL_DIR}/scripts/telegram_send.py --chat-id <CHAT_ID> --token "$BUB_TELEGRAM_TOKEN" --source-is-bot --source-username <USERNAME> --message -
Message to a bot using @username mention.
EOF

# Source message sender is bot without username: use tg://user?id= link
cat << 'EOF' | uv run ${SKILL_DIR}/scripts/telegram_send.py --chat-id <CHAT_ID> --token "$BUB_TELEGRAM_TOKEN" --source-is-bot --source-user-id <USER_ID> --source-display-name "Display Name" --message -
Message to a user/bot using tg://user?id= mention.
EOF

# Edit an existing message
cat << 'EOF' | uv run ${SKILL_DIR}/scripts/telegram_edit.py --chat-id <CHAT_ID> --token "$BUB_TELEGRAM_TOKEN" --message-id <MESSAGE_ID> --text -
Updated content here.
EOF

© bubbuild, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (scripts) in src/skills/telegram of bubbuild/bub.

• SKILL.md
• scripts/telegram_edit.py
• scripts/telegram_rich.py
• scripts/telegram_send.py

Open the folder on GitHubat commit b4a61bf