Telegram — A Plataforma de Bots Mais Popular

Telegram — A Plataforma de Bots Mais Popular

Se você já usou o Telegram, sabe por que ele é um lar tão incrível para bots. É rápido, funciona em qualquer dispositivo e tem uma base de usuários gigantesca. Mas aqui está o detalhe: o Telegram não é apenas um lugar onde bots existem — é um lugar onde seu Hermes Agent pode realmente brilhar.

Assim que você conecta o Hermes ao Telegram, você ganha um bot conversacional completo, com quem pode conversar de qualquer lugar. Envie um áudio e ele é transcrito automaticamente. Peça um relatório agendado e ele chega direto no seu chat. Você pode até adicionar o bot a grupos e fazê-lo participar da conversa. Ele lida com texto, voz, imagens e anexos — tudo através da sólida biblioteca python-telegram-bot.

Vamos passar pela configuração, passo a passo.

Passo 1: Crie Seu Bot com o BotFather

Todo bot do Telegram começa com um token de API do @BotFather, o gerenciador oficial de bots do Telegram. Veja como obter o seu:

1. Abra o Telegram e procure por @BotFather, ou acesse t.me/BotFather
2. Envie /newbot
3. Escolha um nome de exibição — qualquer um que você quiser, como “Hermes Agent”
4. Escolha um nome de usuário — ele deve ser único e terminar com bot (ex.: my_hermes_bot)
5. O BotFather responderá com seu token de API, que se parece com isto:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Mantenha seu token em segredo! Qualquer pessoa com esse token pode controlar seu bot. Se ele vazar, revogue-o imediatamente com /revoke no BotFather.

Passo 2: Personalize Seu Bot (Opcional, Mas Vale a Pena)

Alguns comandos rápidos do BotFather podem deixar seu bot com uma aparência polida e profissional:

Comando	Finalidade
/setdescription	O texto “O que este bot pode fazer?” exibido antes de alguém começar a conversar
/setabouttext	Texto curto na página de perfil do bot
/setuserpic	Enviar um avatar para o seu bot
/setcommands	Definir o menu de comandos (o botão / no chat)
/setprivacy	Controlar se o bot vê todas as mensagens do grupo (veja o Passo 3)

Para /setcommands, um bom conjunto inicial é:

help - Mostra informações de ajuda
new - Inicia uma nova conversa
sethome - Define este chat como canal principal

Indicador de Status Online/Offline (Opcional)

Bots do Telegram não têm o ponto verde “online” como contas de usuário. A coisa mais próxima disso é a descrição curta do bot — a linha abaixo do nome na página de perfil.

Ative status_indicator e o Hermes definirá essa descrição como Online quando o gateway conectar e Offline em um desligamento limpo:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Algumas observações: essa descrição é global (visível para todos os usuários), e apenas um desligamento limpo grava “Offline” — uma falha abrupta deixa o último status. Está desativado por padrão, pois altera o perfil do seu bot.

Prioridade e Limite do Menu de Comandos (Opcional)

O Hermes registra automaticamente seu menu de comandos quando o gateway do Telegram inicia. Por padrão, ele limita a 60 comandos — o suficiente para todos os embutidos mais habilidades comuns. Se você tiver comandos de plugins que devem permanecer visíveis no seletor /, você pode priorizá-los:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

• prepend: seus comandos primeiro, depois os padrões do Hermes
• append: padrões do Hermes primeiro, depois os seus
• replace: usa apenas sua lista para ordenação de prioridade

O Telegram permite até 100 comandos, mas payloads grandes podem falhar. O Hermes usa 60 por padrão para confiabilidade e limita os valores a 1..100.

Passo 3: Modo de Privacidade — Essencial para Grupos

Esta é a fonte nº 1 de confusão ao usar bots em grupos: o modo de privacidade está ATIVADO por padrão.

Com o modo de privacidade ATIVADO, seu bot só vê:

• Mensagens que começam com /
• Respostas às mensagens do próprio bot
• Mensagens de serviço (entradas, saídas, fixações)
• Mensagens em canais onde o bot é administrador

Com o modo de privacidade DESATIVADO, o bot vê todas as mensagens do grupo.

Para desativá-lo:

1. Envie mensagem para @BotFather
2. Envie /mybots
3. Selecione seu bot
4. Vá em Bot Settings → Group Privacy → Turn off

Importante: Você deve remover e adicionar o bot novamente a qualquer grupo após alterar essa configuração. O Telegram armazena em cache o estado de privacidade quando o bot entra no grupo, e ele não será atualizado até ser re-adicionado.

Alternativa: Promova o bot a administrador do grupo. Bots administradores sempre recebem todas as mensagens, sem precisar alternar a privacidade.

Observar Conversas do Grupo Sem Responder Automaticamente

Quer que seu bot veja mensagens do grupo, mas só responda quando for mencionado? Configure assim:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

Mensagens não mencionadas de chats na lista de permissões são adicionadas à transcrição da sessão como contexto observado — mas não acionam o agente. Apenas uma menção posterior @nomadobot realmente dispara uma resposta.

---

É isso! Com esses três passos, você tem um bot do Telegram totalmente funcional, alimentado pelo Hermes Agent. Vá em frente — envie um áudio, adicione-o a um grupo e veja a mágica acontecer.