Como conectar o Hermes Agent ao WhatsApp?

Fala aí, beleza? Pensa no teu agente de IA respondendo no mesmo app onde chega áudio de três minutos da família 😀

O Hermes Agent é um agente de IA open source mantido pela Nous Research, no repositório NousResearch/hermes-agent

E ele tem dois caminhos distintos pra chegar no WhatsApp: uma ponte embutida baseada em Baileys, que roda em cima de uma conta pessoal, e o adaptador da API oficial WhatsApp Business Cloud, da Meta

Os dois colocam o agente dentro do chat, só que as exigências, os limites e o risco são MUITO diferentes

Bora destrinchar cada um?

Ponte Baileys ou API oficial da Meta: qual caminho escolher

Antes de sair rodando comando, vale entender que tu está escolhendo entre duas arquiteturas, não entre duas versões da mesma coisa

A leitura da tabela é simples: se tua dor é subir rápido e testar, a ponte resolve; se tu vai colocar isso na frente de outras pessoas, o caminho oficial é o que a Meta suporta

E se tua praia é montar o fluxo por fora do agente, dá pra atacar o mesmo problema com um agente de IA no WhatsApp com n8n, que é outra abordagem pro mesmo canal

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O que você precisa antes de começar

Aqui a lista muda conforme o caminho, então separei os dois

Pra ponte Baileys:

• um número de WhatsApp (a documentação orienta usar um número dedicado justamente pra isolar o risco da conta pessoal)
• o celular à mão, porque o pareamento é por QR code
• a decisão entre modo self-chat (tu manda mensagem pra ti mesmo e fala com o agente ali) e modo bot com número dedicado, que exige um segundo número com WhatsApp rodando em um aparelho

Pra API oficial WhatsApp Business Cloud:

• conta Meta Business, não WhatsApp pessoal
• número dedicado
• um webhook HTTPS público, porque é por ali que a Meta entrega as mensagens de entrada

Nos dois casos, o arquivo ~/.hermes/.env é o lugar onde mora a configuração de allowlist, aquilo que define quem pode falar com o agente

Como conectar pela ponte Baileys (conta pessoal, passo a passo)

Esse é o caminho de menor atrito, e também o de maior risco

1. Rode o fluxo de configuração da ponte

   hermes whatsapp

Esse comando já cobre a seleção de modo e o pareamento por QR code, então é o ponto de partida

O erro comum deste passo: achar que a ponte usa a API oficial do WhatsApp Business

Ela não usa, ela emula uma sessão do WhatsApp Web, e essa diferença é a origem de quase todo problema que vem depois

2. Escolha o modo de uso

No modo self-chat, tu manda mensagem pra ti mesmo e conversa com o agente naquele chat

No modo bot com número dedicado, as pessoas falam com o número do bot, e aí tu precisa de um segundo número com WhatsApp em um aparelho

3. Pareie lendo o QR do terminal

No celular: WhatsApp > Aparelhos conectados (Linked Devices) > Conectar um aparelho

Aí é só escanear o QR code que o terminal imprimiu, do mesmo jeitinho que tu faz pra abrir o WhatsApp Web

4. Confirme onde a sessão ficou salva

   ls ~/.hermes/platforms/whatsapp/session

A sessão persiste entre reinícios, então tu não precisa reler o QR toda vez que subir o serviço

Guarda esse caminho na cabeça, porque ele volta na seção de segurança e é o ponto mais sensível da integração

5. Suba o serviço de gateway

   hermes gateway

É o gateway de mensageria que mantém o agente ouvindo o canal

Se tu prefere um fluxo guiado em vez de comando específico, existe o assistente interativo de plataformas:

hermes gateway setup

A lista dele inclui Telegram, Discord, Slack, WhatsApp, Signal, Email, entre outros, e tu escolhe WhatsApp ali dentro

Como conectar pela API oficial WhatsApp Business Cloud

Aqui é mais burocrático, porém é o caminho que a Meta suporta

1. Rode o assistente da Cloud API

   hermes whatsapp-cloud

Repara que o comando é OUTRO, diferente do hermes whatsapp da ponte Baileys

Ele percorre cada credencial com validação na hora de colar e gera o verify token pra ti

O erro comum deste passo: colar o número de telefone no campo Phone Number ID

A validação do assistente existe exatamente pra pegar essa confusão antes de tu quebrar a cabeça depois

2. Configure o webhook no painel da Meta

No Meta App Dashboard: WhatsApp > Configuration > Edit na seção Webhook, e depois Verify and save

Nesse momento a Meta faz um GET e o gateway devolve o challenge, é o aperto de mão entre os dois lados

3. Assine o campo de mensagens

Ainda no painel, em Webhook fields, clica em Manage e assina o campo messages

Sem essa assinatura, o webhook até verifica, só que mensagem de entrada nenhuma chega no teu agente

4. Defina quem pode falar com o agente

No caminho oficial a variável é WHATSAPP_CLOUD_ALLOWED_USERS, não a da ponte

5. Suba o gateway

   hermes gateway

O resto do processo é copiar e colar guiado pelo próprio assistente, que termina justamente com as instruções das partes que não dá pra automatizar

Cuidados de acesso: quem fala com o agente e onde ficam suas credenciais

Essa é a parte que a galera pula, e é a que pode te custar caro

Um agente conectado no teu WhatsApp tem acesso ao que chega nele, então controle de acesso não é detalhe, é o passo principal

1. Preencha a allowlist no ~/.hermes/.env

   WHATSAPP_ALLOWED_USERS=5511999999999,5521888888888

Os números vão em formato internacional, SEM o sinal de mais, separados por vírgula

No caminho oficial, a variável equivalente é WHATSAPP_CLOUD_ALLOWED_USERS

O erro comum deste passo: configurar uma e achar que vale pra outra, quando são adaptadores diferentes com variáveis diferentes

2. Entenda o comportamento padrão do gateway

Por padrão, o gateway nega todos os usuários que não estejam na allowlist

Ou seja: o default já joga a favor, o problema começa quando alguém afrouxa isso na mão

3. Trate o curinga como o que ele é

   WHATSAPP_ALLOWED_USERS=*

Isso libera todos os remetentes, e equivale a WHATSAPP_ALLOW_ALL_USERS=true

O erro comum deste passo: deixar o curinga ligado em modo bot, com o número exposto

Pra um teste rápido em self-chat, beleza; com um número que outras pessoas conhecem, é convite aberto

4. Proteja a pasta de sessão

   chmod 700 ~/.hermes/platforms/whatsapp/session

Essa pasta contém chaves de criptografia e credenciais do dispositivo, e dá acesso total à tua conta de WhatsApp

A documentação orienta não compartilhar e não commitar essa pasta, e olha que já vi gente subir .env inteiro pro GitHub sem perceber, então dá aquela conferida no .gitignore

Vale lembrar que o próprio projeto já apertou esse ponto: o PR #21291 (fix(whatsapp): reject strangers by default, never respond in self-chat) fechou a issue #8389 e passou a descartar em silêncio, no bridge JS, mensagens de estranhos em modo bot sem allowlist, em vez de devolver código de pareamento pra elas

A mudança entrou na release v0.13.0 (v2026.5.7)

Fechar o círculo de quem conversa com o agente é o mesmo cuidado que vale em qualquer projeto de agentes inteligentes multicanal, independente da stack

O que o agente consegue fazer dentro do WhatsApp

Conectar é meio caminho, agora vamos ao que a integração entrega no dia a dia

Áudio recebido vira texto, e a resposta pode voltar em áudio

Mensagens de voz recebidas (.ogg opus) são transcritas pelo provedor de STT que tu configurou: faster-whisper local, Groq Whisper ou OpenAI Whisper

E respostas com TTS saem como anexo de áudio MP3

Na prática, aquele áudio quilométrico vira input do agente sem tu precisar transcrever na mão

Imagem entra como entrada do agente

Imagens são baixadas automaticamente e anexadas à entrada do agente

Modelos com visão nativa leem a imagem direto, e modelos sem visão recebem uma descrição textual gerada automaticamente

Efeito prático: mandar print de erro no chat funciona, e o resultado varia conforme o modelo que tu escolheu

Resposta longa sai fatiada

Respostas longas são divididas em blocos de 4.096 caracteres por mensagem

Então não estranha ver o agente respondendo em duas ou três mensagens seguidas, é o adaptador respeitando o limite por mensagem

Mensagens em sequência viram um pedido só

Mensagens de texto sucessivas do mesmo chat são bufferizadas e enviadas como um pedido único depois de um período de silêncio

O padrão é 5 segundos, estendido pra 10 segundos em fragmentos muito longos

Isso é ótimo pra quem escreve igual eu, em quatro mensagens picadas, porque o agente responde entendendo o conjunto e não cada pedacinho solto 🙂

Limites e problemas comuns da integração

Envio falha com erro Graph 131047

Sintoma: a mensagem simplesmente não sai, e a API responde com o erro Graph 131047 (Re-engagement message)

Causa: passou a janela de 24 horas após a última mensagem recebida do usuário

Solução: fora dessa janela, a Cloud API só aceita template pré-aprovado, então é por template que tu volta a falar

Prevenção: desenhe o fluxo contando com essa janela, e não com envio livre a qualquer hora

Agente não responde em grupo pelo caminho oficial

Sintoma: funciona na conversa direta, e no grupo o agente fica mudo

Causa: o adaptador whatsapp_cloud trata apenas mensagens diretas na v1

Solução: usar conversa direta nesse caminho, porque o suporte a grupo na Cloud API é limitado e gatilhado por camada de capacidade da Meta

Prevenção: se grupo é requisito do teu caso, valide isso ANTES de montar toda a infra de webhook

A ponte para de funcionar do nada

Sintoma: estava tudo redondo e, de repente, a ponte deixou de conectar

Causa: o WhatsApp atualiza o protocolo do Web periodicamente, e isso pode quebrar temporariamente a compatibilidade de pontes de terceiros

Solução: acompanhar o repositório do projeto, já que a correção vem do lado da ponte

Prevenção: não coloca nada crítico dependendo só da ponte, porque essa quebra não está no teu controle

Conta restrita ou banida

Sintoma: a conta usada na ponte é limitada ou bloqueada

Causa: o WhatsApp não suporta oficialmente bots de terceiros fora da Business API

Solução: o caminho suportado é o adaptador oficial da Cloud API

Prevenção: a própria documentação orienta usar um número dedicado pra isolar o risco da tua conta pessoal, e esse conselho é barato demais pra ignorar

Conclusão

No fim, a escolha do caminho pro Hermes Agent no WhatsApp é entre rápido e arriscado ou oficial e burocrático

A ponte Baileys sobe em minutos com hermes whatsapp, sem conta de desenvolvedor Meta, porém carrega risco de restrição da conta e depende de um protocolo que muda sem avisar

A Cloud API pede conta Meta Business, número dedicado e webhook HTTPS público, e em troca te dá o caminho suportado, com a janela de 24 horas e os templates como regra do jogo

O próximo passo concreto é: escolhe o caminho, roda hermes gateway setup ou o comando específico do adaptador, fecha a allowlist ANTES de expor o número e protege a pasta de sessão com chmod 700

Quem inverte essa ordem é quem descobre da pior forma que aquela pasta dá acesso total à conta…

Até o próximo post! 😀