Telegram

Quando Usar

• Use quando precisar enviar uma mensagem, arquivo ou alerta do Telegram de um fluxo de trabalho, hook, job cron ou pipeline de CI
• Use quando uma tarefa de longa duração precisar te notificar ou pedir aprovação no seu telefone (perguntas com botões inline que esperam pela resposta)
• Use ao implementar o comportamento "me notifique quando terminar" ou "me pergunte antes de prosseguir" em sessões automatizadas

Envie atualizações, alertas e arquivos para o Telegram; leia respostas; execute fluxos de "perguntar e esperar" para aprovação. Puro bash + curl + jq — nenhuma instalação além de um token de bot.

Primeira execução: bash scripts/telegram.sh setup (passeio guiado pelo BotFather).

Portão de Segurança

Antes de configurar, enviar uma mensagem ou arquivo, ler respostas ou habilitar um hook, obtenha a aprovação explícita do usuário para o chat de destino, conta do bot e conteúdo ou arquivo exato. Nunca envie dados de espaço de trabalho, cliente, credenciais ou segredos automaticamente. Trate um token como um segredo: não o exiba, não o envie para o repositório, nem o coloque no histórico do shell.

Comandos

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

Configuração

Variáveis de ambiente ganham, depois ~/.config/telegram/config (modo 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)

Respostas e confirmações só são aceitas de IDs de chat configurados. Chats privados preservam o comportamento de chat direto (o ID do usuário remetente deve ser igual ao ID do chat). Como um ID de chat de grupo é compartilhado por todos os membros, ask falha em fechar para grupos, a menos que TELEGRAM_APPROVER_IDS ou o APPROVERS_<NAME> específico do destino liste explicitamente os IDs de usuário do Telegram permitidos a responder.

Hooks de Código Claude (settings.json)

Ping seu telefone quando o Claude precisar de entrada e quando terminar:

{
  "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"}]}]
  }
}

Portão de aprovação em qualquer script/automação:

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

Limitações

• Telegram é um serviço de terceiros: o conteúdo de mensagens e arquivos sai da máquina local e pode ser retido sob as políticas do Telegram.
• Esta habilidade não pode verificar se um ID de chat pertence ao destinatário pretendido; confirme o destino antes de cada novo destino ou automação.
• Tokens de bot concedem controle sobre o bot. Armazene-os apenas em um local de segredos local protegido ou arquivo de configuração modo-600. O script fornece URLs de API contendo tokens para o curl via stdin em vez de argumentos de processamento; rotacione um token se a exposição for suspeita.
• Não use os exemplos para criar notificações não supervisionadas ou fluxos de aprovação sem a autorização explícita e atual do usuário.