O agente no Telegram e no Discord

Três peças para um canal funcionar

Um canal depende de três coisas. Quando uma conversa fica sem resposta, confira cada uma delas. A primeira é o bot, criado na própria plataforma, que entrega um token. A segunda é a liberação de acesso: o gateway recusa os usuários que estão fora da lista de IDs e não foram pareados. A terceira é o gateway rodando como serviço na VPS, conectado à plataforma.

O bot é só uma identidade na plataforma. O gateway na sua VPS processa as mensagens e usa o token para falar em nome do bot. Por isso o mesmo bot não pode ser usado em dois profiles: dois processos lendo o mesmo token disputam as mensagens. Nesse caso, o gateway estaciona o canal repetido.

Telegram ou Discord

As duas plataformas funcionam com o mesmo gateway e o mesmo assistente de configuração, hermes gateway setup. A diferença está em como cada uma cria o bot e se comporta em grupos e servidores com vários participantes.

Para uso individual, o Telegram é o caminho mais curto: o bot fica pronto numa conversa com o @BotFather e o celular já serve de terminal. O Discord exige mais passos no portal. Num servidor com vários participantes, ele abre um tópico para cada conversa com o bot.

Onde ficam os tokens e as listas

O assistente do gateway grava tudo no .env do profile. Você não precisa editar o arquivo à mão, mas precisa saber o que cada linha faz quando o bot não responde.

~/.hermes/.env

Telegram

TELEGRAM_BOT_TOKEN=

o token que o @BotFather entrega ao criar o bot

TELEGRAM_ALLOWED_USERS=

os IDs numéricos dos usuários autorizados a conversar, separados por vírgula

TELEGRAM_GROUP_ALLOWED_CHATS=

os IDs dos grupos liberados por inteiro, números negativos

Discord

DISCORD_BOT_TOKEN=

o token gerado em Reset Token, na página Bot da aplicação

DISCORD_ALLOWED_USERS=

os IDs numéricos dos usuários autorizados a conversar

DISCORD_FREE_RESPONSE_CHANNELS=

os canais onde o bot responde sem precisar de menção

Em profiles diferentes, cada .env guarda o próprio token. Um profile criado com --clone não leva os canais do profile de origem: o comando avisa quais plataformas ficaram para trás. Crie um bot novo para o profile clonado.

Conversas em grupo e em servidor

Num grupo do Telegram, o modo de privacidade vem ligado. Com ele, o bot só enxerga comandos com /, respostas às mensagens dele e avisos do sistema. Para o bot ler as mensagens comuns, desligue a opção no @BotFather, em /mybots, no bot, em Bot Settings e Group Privacy, depois remova o bot do grupo e adicione de novo. A opção telegram.require_mention: true faz o caminho inverso: o bot ignora a conversa e só responde quando é mencionado ou quando um participante responde a uma mensagem dele.

No Discord, o bot responde a tudo nas mensagens diretas e, nos canais de um servidor, só quando é mencionado. Cada menção abre um tópico. Dentro dele, o bot continua respondendo sem nova menção. Com DISCORD_AUTO_THREAD=false, ele responde no próprio canal. Com DISCORD_THREAD_REQUIRE_MENTION=true, volta a exigir menção dentro do tópico, o que evita respostas cruzadas quando vários bots dividem o mesmo tópico.

Quando o bot não responde

Mande a mensagem de novo enquanto acompanha o serviço com journalctl --user -u hermes-gateway -f. O registro mostra em qual peça a mensagem parou:

• Nada aparece no registro: o gateway não está conectado. Confira com hermes gateway status e reinicie com hermes gateway restart.
• A mensagem chega e é recusada: o seu ID não está na lista do .env, ou você usou o nome de usuário no lugar do número.
• O Discord recusa a conexão: falta o Message Content Intent na página Bot da aplicação.
• No grupo do Telegram, o bot só vê comandos: o modo de privacidade está ligado, ou o bot não foi readicionado depois da mudança.

O gateway também aceita o pareamento no lugar da lista: um contato novo recebe um código e você aprova na VPS com hermes pairing approve telegram CODIGO. A área de gateways explica as duas formas de liberar acesso.