Hermes Agent no WhatsApp não conecta: soluções

O bot nunca responde e os logs estão mudos

Você ligou o Hermes Agent ao WhatsApp, o gateway sobe sem erro e o número para o qual você escreve fica parado como uma pedra. Nenhum evento entrante nos logs, nenhum recibo de entrega no celular, nenhuma pista clara sobre qual das dez peças móveis está quebrada. O WhatsApp é o canal mais frágil do stack do Hermes, e quase todos os casos de conexão silenciosa se reduzem a uma de quatro causas.

Três das quatro falham em silêncio por design, e por isso o setup parece correto enquanto nada funciona. Este post percorre cada causa, como confirmar que é a sua e a correção exata. Comece pela primeira - a ordem importa, porque é ela que vem pegando todo mundo desde maio de 2026.

Causa 1: o WhatsApp Shortcake quebrou sua biblioteca de QR

Se você está rodando o Hermes Agent com Baileys, WAHA ou qualquer outra biblioteca que raspe o WhatsApp Web, e o QR se recusa a parear ou desloga o bot logo em seguida, você está batendo no rollout do Shortcake para dispositivos vinculados. O WhatsApp agora exige uma passkey WebAuthn no dispositivo vinculado, e um servidor headless não tem passkey para apresentar: navigator.credentials.get() falha e o link é rejeitado com um 428.

Sintoma: o QR desenha, seu celular escaneia, e ou o pareamento nunca termina ou a sessão morre em poucos minutos. Sessões antigas que reconectavam sozinhas começaram a devolver Stream Errored (conflict) depois de maio de 2026 pelo mesmo motivo. Se funcionava em abril e parou de um dia para o outro, esta é a sua causa.

A correção tem duas formas:

Mude para a Cloud API oficial. É o caminho suportado, não é vulnerável a Meta quebrar uma biblioteca de scraping numa terça qualquer, e é o que o resto do post assume. Configure o Hermes Agent com WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID e WHATSAPP_WEBHOOK_VERIFY_TOKEN no lugar do fluxo QR. O guia de deploy no WhatsApp percorre a dança completa de credenciais.
Continue no Baileys se não tiver alternativa e fixe o commit exato que ainda funciona (os mantenedores acompanham workarounds da passkey na issue #2672). Aceite que a próxima mudança da Meta te quebra de novo. Não é a escolha certa para nada de que você dependa de verdade.

O resto do post cobre o caminho da Cloud API.

Causa 2: sua WABA não está assinada no seu app

É a falha mais comum da Cloud API e a mais silenciosa. Você coloca a URL do webhook no App Dashboard, o GET de verificação passa, a Meta mostra um tique verde ao lado do endpoint, e nenhum evento de mensagem chega.

O que acontece: fixar a URL do webhook no app é só metade da fiação. Cada WhatsApp Business Account (WABA) precisa se inscrever separadamente naquele app para que as mensagens sejam roteadas ao seu endpoint. O App Dashboard não mostra essa assinatura em lugar nenhum, e a UI do webhook deixa você terminar o setup sem WABA anexada. A Meta chama isso de problema de shadow delivery e a correção é uma chamada de API que o assistente de setup não menciona.

Cheque primeiro:

curl -s "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

Se o array data estiver vazio ou não contiver o ID do seu app, esse é o seu problema.

A correção:

curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer $WHATSAPP_ACCESS_TOKEN"

A chamada devolve {"success": true} e a próxima mensagem entrante chega no webhook do Hermes Agent em segundos. Não precisa reiniciar o gateway. Se você rotacionar o access token depois, rode essa chamada de novo: a assinatura fica atrelada ao app mas a escrita exige um token com a permissão whatsapp_business_management.

Causa 3: você ainda está usando o token temporário de 24 horas

O token que a Meta mostra na tela de setup do WhatsApp expira em exatas 24 horas. Se você copiou isso no .env do Hermes Agent na terça à tarde e o bot mudou na quarta à tarde, é por isso.

Sintoma: seu gateway loga OAuthException ou HTTP 401 no próximo envio saída depois da expiração. As chamadas de webhook entrantes da Meta continuam chegando (não precisam do seu token), mas cada resposta que o Hermes tenta postar de volta falha, então o bot recebe sua mensagem, gera uma resposta e a perde no caminho.

A correção é um token permanente de System User, não um token temporário mais longo:

No Meta Business Suite abra Users depois System Users e crie um novo System User com o papel Admin.
Atribua seu app do WhatsApp e sua WhatsApp Business Account a esse System User com Full control.
Clique em Generate new token, escolha seu app e marque whatsapp_business_messaging (preciso para enviar) e whatsapp_business_management (preciso para a chamada subscribed_apps da Causa 2).
Ponha a expiração em Never. Copie o token, coloque em WHATSAPP_ACCESS_TOKEN, reinicie o gateway.

Confira antes de sair de perto:

curl -s "https://graph.facebook.com/v20.0/me?access_token=$WHATSAPP_ACCESS_TOKEN"

Deve devolver o ID e o nome do seu System User, não um erro de OAuth.

Causa 4: você está enviando para o Phone Number ID errado

A Cloud API do WhatsApp usa três IDs e todos são fáceis de confundir: o número de telefone em si, o Phone Number ID e o WABA ID. O Hermes Agent precisa do Phone Number ID, não do número. Se você jogou o número em WHATSAPP_PHONE_NUMBER_ID, cada chamada de saída devolve Object with ID '+55...' does not exist e cada entrada chega sem rota de resposta.

Confuso: o Phone Number ID é um número de 15 ou 16 dígitos que se parece muito com um telefone. Não é.

Onde encontrar: no App Dashboard, abra WhatsApp depois API Setup. O dropdown From lista seus números registrados. Debaixo de cada número, em letra pequena, tem um campo chamado Phone number ID. Esse é o valor que o Hermes Agent precisa.

Confirme se o valor que você tem é real:

curl -s "https://graph.facebook.com/v20.0/$WHATSAPP_PHONE_NUMBER_ID?access_token=$WHATSAPP_ACCESS_TOKEN"

Um ID válido devolve display_phone_number, verified_name e quality_rating. Um ID errado devolve um erro do Graph API cuja mensagem cita o ID que não conseguiu achar.

Já que está aqui, cheque a variável WHATSAPP_BUSINESS_ACCOUNT_ID: é um ID separado da WABA dona do número, usado pela chamada de assinatura da Causa 2, e é fácil trocar os dois quando você copia do dashboard.

Duas armadilhas extras que vale descartar

Se as quatro causas acima estão limpas e as mensagens seguem sem fluir, cheque essas em seguida:

O app está travado em modo Dev. O WhatsApp só entrega webhooks de mensagens que o dono do app enviou ou recebeu nas últimas 24 horas, e só de números adicionados explicitamente em WhatsApp depois API Setup depois To. Passe o app para Live em App Review quando estiver pronto para tráfego real.
O campo webhook messages não está assinado. Em WhatsApp depois Configuration, olhe a seção Webhook fields e confirme que messages tem um tique verde. A Meta deixa você salvar uma URL de webhook sem campos assinados, e silenciosamente não entrega nada.

Ordem de diagnóstico que economiza tempo

Quando o bot mudar, atravesse as causas nesta ordem em vez de reinstalar tudo:

Você está no caminho QR? Se sim, migre para a Cloud API antes de gastar mais um minuto em qualquer outra coisa. O Shortcake não vai embora.
Sua WABA está assinada no seu app? A única chamada curl acima responde em três segundos. Maior taxa de acerto em deploys de Cloud API.
Cheque o token. curl /me falha na hora se o token está morto, errado ou sem escopos.
Verifique o Phone Number ID. curl /$PHONE_NUMBER_ID devolve os campos do número quando é válido.
Cheque o modo Dev e os campos assinados. Mais lento de inspecionar, menos comum como causa raiz, mas vale descartar antes de abrir um ticket com a Meta.

Para o caminho completo de instalação inicial, veja o guia de deploy do Hermes Agent no WhatsApp. Se o Telegram encaixaria no seu caso, a comparação Telegram vs WhatsApp percorre os tradeoffs antes de você se comprometer.

Quando você prefere não brigar com a Meta toda semana

A Meta lança mudanças na UI do webhook, aperta a verificação e quebra o caminho QR no ritmo dela. Se, para você, um agente de IA pessoal não deveria exigir uma conta do Business Manager e um token de System User para responder oi de volta, comece com a Hermify. A Hermify roda um Hermes Agent gerenciado no Telegram com a mesma memória e as mesmas skills, no ar em cerca de um minuto, sem a configuração da Meta para cuidar.