name: telegram-bot-messaging
description: “Send Telegram messages, files, and alerts via bot API; ask questions with inline buttons and wait for the answer. Supports multiple bots, named chat targets, and CI/cron/hook notifications.”
category: productivity
risk: critical
source: https://github.com/sanjay3290/ai-skills/tree/main/skills/telegram
source_repo: sanjay3290/ai-skills
source_type: community
date_added: “2026-07-09”
author: sanjay3290
tags: [telegram, notifications, bots, approvals]
tools: [claude, cursor, gemini]
license: “Apache-2.0”
license_source: “https://github.com/sanjay3290/ai-skills/blob/main/LICENSE”

Telegram

何时使用

• 当需要从工作流、钩子、cron 任务或 CI 流水线发送 Telegram 消息、文件或提醒时使用
• 当长时间运行的任务应在手机上通知你或请求你批准时使用（内联按钮提问并等待回答）
• 当把"完成后通知我"或"继续前先问我"的行为接入自动化会话时使用

向 Telegram 发送更新、提醒和文件；读取回复；运行提问并等待的
审批流程。纯 bash + curl + jq —— 除了机器人令牌外无需安装。

首次运行: bash scripts/telegram.sh setup（引导式 BotFather 演练）。

安全闸门

在设置、发送消息或文件、读取回复或启用钩子之前，请先获得
用户对目标聊天、机器人账号以及确切内容或文件的明确批准。切勿
自动发送工作区、客户、凭据或机密数据。将令牌视为机密：
不要回显它、不要提交它、也不要让它出现在 shell 历史中。

命令

bash scripts/telegram.sh send "Deploy finished ✅"                    # basic alert
bash scripts/telegram.sh send "low priority" --silent                # no notification sound
bash scripts/telegram.sh send "*bold* alert" --format md             # MarkdownV2 (falls back to plain)
bash scripts/telegram.sh send "hi" --to alerts --bot work            # named target + named bot
bash scripts/telegram.sh file report.pdf "Q3 report"                 # document (photos auto-detected)
bash scripts/telegram.sh read                                        # new incoming messages since last read
ANSWER=$(bash scripts/telegram.sh ask "Deploy to prod?" --options "Yes,No" --timeout 300)
# exit 0 = answered (stdout = answer), 2 = timeout

配置

环境变量优先，其次为 ~/.config/telegram/config（权限 600）：

TELEGRAM_BOT_TOKEN=123:ABC...     # default bot
TELEGRAM_CHAT_ID=987654321        # default target
BOT_ALERTS_TOKEN=456:DEF...       # --bot alerts   (add via: setup --bot alerts)
TARGET_FAMILY=-100987...          # --to family    (any chat/group/channel id)
TELEGRAM_APPROVER_IDS=123456789   # default group approver user IDs (comma-separated)
APPROVERS_FAMILY=123456789,987654321 # approvers for --to family (overrides default)

回复和回答仅接受来自已配置聊天 ID 的消息。私聊保持
直接聊天行为（发送者用户 ID 必须等于聊天 ID）。由于群聊 ID 被
每个成员共享，除非 TELEGRAM_APPROVER_IDS 或目标特定的
APPROVERS_<NAME> 明确列出了允许回答的 Telegram 用户 ID，否则群聊中的 ask 会以失败关闭。

Claude Code 钩子（settings.json）

当 Claude 需要输入以及完成时，通知你的手机：

{
  "hooks": {
    "Notification": [{"hooks": [{"type": "command",
      "command": "bash ~/.claude/skills/telegram/scripts/telegram.sh send \"🔔 Claude needs input in $(basename \\\"$PWD\\\")\""}]}],
    "Stop": [{"hooks": [{"type": "command",
      "command": "bash ~/.claude/skills/telegram/scripts/telegram.sh send \"✅ Claude finished in $(basename \\\"$PWD\\\")\" --silent"}]}]
  }
}

任何脚本/自动化中的审批闸门：

if [ "$(bash scripts/telegram.sh ask 'Deploy to prod?' --options 'Yes,No')" = "Yes" ]; then
  ./deploy.sh
fi

局限性

• Telegram 是第三方服务：消息和文件内容会离开本地机器，并且可能
  根据 Telegram 的政策被保留。
• 此技能无法验证聊天 ID 是否属于预期的接收者；在每次新的
  目的地或自动化之前确认目标。
• 机器人令牌赋予对机器人的完全控制权。仅将它们存储在受保护的本地机密存储或
  权限 600 的配置文件中。脚本通过
  stdin 而非进程参数将包含令牌的 API URL 提供给 curl；如果怀疑令牌泄露，请轮换它。
• 未经用户明确、当前的授权，不要使用示例创建无人值守的通知或审批流程。