MÓDULO 2.4

📱 Telegram: BotFather + autorização

O caminho de menor fricção pra colocar o agente no seu bolso. BotFather, user ID, gateway setup, primeira conversa e debug se algo der errado.

6
Tópicos
25
Minutos
Prático
Nível
Setup
Tipo
1

🚀 Por que começar pelo Telegram

Hermes suporta 20+ plataformas de mensagem — Discord, Slack, WhatsApp, Signal, Teams, Matrix, iMessage. Mas Telegram é onde você deve começar. Setup em 5 minutos contra 30+ minutos das outras.

⚡Comparação de fricção

  • Telegram: @BotFather no chat, 30 segundos pro token. Sem cadastro extra.
  • Discord: developer portal, criar app, criar bot, configurar intents, gerar invite link.
  • Slack: criar app no api.slack.com, configurar OAuth scopes, instalar no workspace.
  • WhatsApp: via gateway pago (Whapi) ou Meta Business Manager — burocrático.
  • iMessage: requer Mac em casa rodando BlueBubbles 24/7.

📦O que você ganha de quebra

  • Voice notes que o Hermes transcreve e responde com TTS
  • Comandos slash /cron, /usage, /skills, /compress
  • Compartilhamento de imagens (vision automático)
  • Compartilhamento de arquivos PDF, áudio, vídeo
  • Cliente desktop e mobile sincronizados
2

🤖 Criar bot com BotFather

BotFather é um bot oficial do próprio Telegram que cria outros bots. Sem developer portal, sem aprovação, sem cadastro. 5 mensagens trocadas no chat e você tem o token.

📝 Sequência completa

  1. No Telegram, busque @BotFather e abra o chat.
  2. Envie /newbot.
  3. Ele pergunta o nome (display): ex. "Hermes Pessoal".
  4. Ele pergunta o username: precisa terminar em bot e ser único globalmente. Ex.: hermes_pessoal_xyz_bot.
  5. Ele devolve o token: algo como 1234567890:AAH.... É a credencial completa do bot.

🔒Tratamento do token

  • Token = senha do bot. Quem tiver controla integralmente.
  • Nunca cole em chat público, fórum, repositório, GitHub, screenshot.
  • Use hermes config set TELEGRAM_TOKEN xxx dentro do container — escreve com auto-redação nos logs.
  • Se vazar: /revoke no BotFather gera novo token e invalida o antigo.

🎨Customizações úteis no BotFather

  • /setdescription — texto que aparece quando alguém abre o bot
  • /setuserpic — foto de perfil
  • /setcommands — lista de comandos slash que aparece no Telegram
  • /setprivacy — em grupos, define se o bot vê todas mensagens ou só @menções
3

🆔 Pegar seu user ID via @userinfobot

Hermes precisa saber quem está autorizado a falar com ele. Sem essa configuração, o bot ou aceita qualquer um (perigoso) ou ignora você (frustrante). A forma estável de identificação é o user ID numérico — não o username, que pode mudar.

🔍 Como descobrir seu ID

  1. No Telegram, busque @userinfobot.
  2. Envie qualquer mensagem (ou /start).
  3. Ele responde com seu ID numérico (ex: 123456789), nome, idioma, etc.
  4. Anote esse ID — ele é usado em TELEGRAM_AUTHORIZED_USERS.

👥IDs de grupos e canais

Para grupos, o ID começa com -100... (negativo). Adicione o bot como membro e use @RawDataBot ou similar pra capturar o group ID. Útil pra usar Hermes em chat compartilhado com cônjuge/sócio.

💡Múltiplos usuários autorizados

TELEGRAM_AUTHORIZED_USERS aceita lista separada por vírgula: 123456789,987654321. Útil pra compartilhar agente com pequena equipe — mas lembre que cada um tem acesso completo. Pra equipes maiores, separar por agente é mais seguro.

4

⚙️ hermes gateway setup

Com token e user ID em mãos, é hora de conectar tudo. hermes gateway setup abre um wizard interativo dentro do container — guiado, com validação a cada passo.

🪄 Wizard passo-a-passo

# Entre no container
docker exec -it hermes hermes gateway setup

# O wizard pergunta:
# 1) Qual plataforma? → telegram
# 2) Cole o bot token: → 1234567890:AAH...
# 3) Cole user ID(s) autorizado(s): → 123456789
# 4) Home channel (canal padrão pra crons): → 123456789

# Depois, suba o gateway
hermes gateway start

📂O que o wizard salva onde

  • ~/.hermes/.env — variáveis sensíveis (TELEGRAM_TOKEN)
  • ~/.hermes/config.yaml — configurações do gateway, autorização
  • TELEGRAM_HOME_CHANNEL: destino padrão de entregas automáticas (crons sem --deliver)
  • TELEGRAM_AUTHORIZED_USERS: lista de IDs que podem mandar comando

🔄 Comandos relacionados

  • hermes gateway status — gateway está rodando?
  • hermes gateway start — sobe o gateway (ou re-sobe após restart)
  • hermes gateway stop — para o gateway
  • hermes gateway setup — re-roda wizard se quiser ajustar
5

💬 Primeira conversa + debug

Hora da verdade. Abra o chat com seu bot no Telegram, mande "Olá". Resposta esperada: o agente responde apresentando-se. Se passar, todo o setup está OK. Se falhar, os logs mostram o erro objetivo.

🐛 Comandos de debug

# Status do gateway
docker exec hermes hermes gateway status

# Logs em tempo real
docker exec hermes tail -f /root/.hermes/logs/gateway.log

# Verificar variáveis carregadas
docker exec hermes env | grep TELEGRAM

# Testar conexão com API do Telegram
docker exec hermes curl -s https://api.telegram.org/bot$TELEGRAM_TOKEN/getMe

🚨Erros mais comuns

  • "401 Unauthorized": token errado, com espaço extra ou caractere copiado a mais. Refazer config set.
  • "user not authorized": seu ID não está em TELEGRAM_AUTHORIZED_USERS. Confira @userinfobot e refaça setup.
  • "connection timeout": firewall do VPS bloqueando saída pra api.telegram.org. Cheque ufw outgoing.
  • Sem resposta nem erro: gateway pode estar parado. hermes gateway start.
  • Bot responde mas demora: provedor de inferência sem créditos ou rate-limited. Cheque /usage.

✓Aplicação da mentalidade T1.2

Se nada funcionou, copie o erro do log e cole na CLI do Hermes (docker exec -it hermes hermes): "Esse erro apareceu quando tentei o gateway. Diagnostique e proponha correção." Ele lê a doc, identifica o sintoma, sugere fix.

6

🎚️ Customização: voice, slash, permissões

Conexão funcionando. Agora vale entender 3 capacidades que mudam muito a experiência: voice notes, comandos slash e o sistema de permissões (allow once/session/always).

🎤 Voice notes

Aperte e segure o microfone no Telegram, fale, solte. O Telegram envia áudio. Hermes transcreve, processa, e pode responder com texto OU com TTS de volta. Útil em movimento — andando, dirigindo, cozinhando.

⌨️ Comandos slash mais úteis

  • /cron list — todos os jobs agendados
  • /cron add "every 1d at 09:00" "Resumo diário" — cria cron
  • /skills — lista skills disponíveis
  • /usage — quantos tokens gastos na sessão
  • /compress — força compressão de contexto
  • /help — guia rápido dentro do chat

🔐Sistema de permissões

  • Allow once: só essa execução. Bom pra ação destrutiva única (apagar arquivo, force push).
  • Allow session: dentro da sessão atual. Bom pra exploração ("vou fazer várias edições agora").
  • Allow always: persistente em ~/.hermes/permissions.json. Bom pra ações recorrentes seguras (git commit/push em repo seu).

⚠️Use "always" com critério

Marcar tudo como "always allow" anula o sistema de proteção. Use só pra ações repetidas, em escopo travado, com baixo risco. Auditar regularmente: hermes permissions list.

🎯Resumo do módulo

✓
Telegram tem a menor fricção pra começar — BotFather entrega token em 30 segundos.
✓
BotFather: /newbot, nome, username, token — trate o token como senha.
✓
@userinfobot dá seu user ID estável — único, numérico, permanente.
✓
hermes gateway setup é o wizard guiado — token, user ID, home channel.
✓
Voice, slash commands, permissões granulares — capacidades que mudam a experiência.

Próximo módulo:

2.5 - 🐙 GitHub: token, .gitignore, hermes config set

← Módulo Anterior Próximo Módulo →