Novidades na Configuração do WhatsApp no Hermes

Se você tem acompanhado nossa série sobre o Hermes Agent, sabe que adoramos simplificar as coisas. Hoje, vamos mergulhar na configuração atualizada do WhatsApp — e há uma grande mudança nos bastidores.

O Hermes agora se conecta ao WhatsApp através de uma ponte integrada baseada no Baileys. Pense nisso como uma emulação de uma sessão do WhatsApp Web. Sem conta de desenvolvedor Meta, sem verificação de negócios, sem URL pública — apenas você, seu celular e um QR code.

Início rápido: Execute hermes gateway setup e escolha WhatsApp para um passo a passo guiado.

Duas Integrações com o WhatsApp — Entenda a Diferença

Antes de continuarmos, vamos esclarecer um ponto comum de confusão. Existem duas maneiras de conectar o WhatsApp ao Hermes:

Integração	Ideal para	Requer
Ponte Baileys (este guia)	Bots pessoais, testes rápidos, sem URL pública	Apenas um celular com WhatsApp
WhatsApp Business Cloud API	Bots empresariais reais, estabilidade, risco zero de banimento	Conta Meta Business, URL pública de webhook

A ponte Baileys é não oficial — ela carrega um pequeno risco de banimento. A Business Cloud API é o caminho oficial suportado pela Meta. Você pode até mesmo executar ambas em paralelo em números de telefone diferentes, se precisar.

⚠️ Dois Avisos Importantes

Risco de banimento: O WhatsApp não suporta oficialmente bots de terceiros fora da Business API. Para se manter seguro:

Use um número de telefone dedicado para o bot (não o seu pessoal)
Não envie mensagens em massa ou spam — mantenha o tom conversacional
Não automatize mensagens de saída para pessoas que não enviaram mensagem primeiro

Atualizações de protocolo: O WhatsApp atualiza periodicamente seu protocolo Web, o que pode quebrar temporariamente pontes de terceiros. Se o seu bot parar de funcionar após uma atualização do WhatsApp, basta baixar a versão mais recente do Hermes e reconectar.

Dois Modos — Escolha Seu Estilo

Modo	Como funciona	Ideal para
Número de bot separado (recomendado)	Dedique um número ao bot; as pessoas enviam mensagem diretamente para ele	UX limpa, múltiplos usuários, menor risco de banimento
Conversa pessoal (self-chat)	Use seu próprio WhatsApp; envie mensagem para si mesmo para conversar com o agente	Configuração rápida, usuário único, testes

Pré-requisitos

Node.js v18+ e npm — a ponte roda como um processo Node.js
Um celular com WhatsApp instalado (para escanear o QR code)

Boas notícias: a ponte atual baseada no Baileys não requer mais Chromium ou Puppeteer. Muito mais leve.

Passo 1: Execute o Assistente de Configuração

hermes whatsapp

O assistente irá:

Perguntar qual modo você deseja (bot ou self-chat)
Instalar as dependências da ponte, se necessário
Exibir um QR code no seu terminal
Aguardar você escaneá-lo

Para escanear o QR code:

Abra o WhatsApp no seu celular
Vá em Configurações → Aparelhos conectados
Toque em Conectar um aparelho
Aponte a câmera para o QR code no terminal

Após a conexão, o assistente confirma a conexão e encerra. Sua sessão é salva automaticamente.

Dica: Se o QR code aparecer distorcido, certifique-se de que seu terminal tenha pelo menos 60 colunas de largura e suporte Unicode.

Passo 2: Obtendo um Segundo Número de Telefone (Modo Bot)

Para o modo bot, você precisa de um número ainda não registrado no WhatsApp. Três opções:

Opção	Custo	Observações
Google Voice	Grátis	Apenas EUA. Verifique o WhatsApp via SMS pelo aplicativo Google Voice.
SIM pré-pago	US$ 5–15 (pagamento único)	Ative, verifique, e o SIM pode ficar guardado na gaveta. Faça uma chamada a cada 90 dias para mantê-lo ativo.
Serviços VoIP	Grátis–US$ 5/mês	TextNow, TextFree, etc. Alguns números são bloqueados pelo WhatsApp — tente alguns.

Depois de obter o número:

Instale o WhatsApp em um celular (ou use o aplicativo WhatsApp Business com dual-SIM)
Registre o novo número
Execute hermes whatsapp e escaneie o QR code dessa conta

Passo 3: Configure o Hermes

Adicione isto ao seu arquivo ~/.hermes/.env:

# Obrigatório
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot                          # "bot" ou "self-chat"

# Controle de acesso — escolha UM:
WHATSAPP_ALLOWED_USERS=15551234567         # Números separados por vírgula (código do país, sem +)
# WHATSAPP_ALLOWED_USERS=*                 # OU permitir todos
# WHATSAPP_ALLOW_ALL_USERS=true            # OU defina esta flag (equivalente a *)

Atalho para permitir todos: Definir WHATSAPP_ALLOWED_USERS=* permite todos os remetentes — equivalente a WHATSAPP_ALLOW_ALL_USERS=true. Para usar o fluxo de pareamento, remova ambas as variáveis e confie no sistema de pareamento por DM.

Configurações opcionais em ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

pair (padrão global) envia um código de pareamento para remetentes de DM desconhecidos.
ignore mantém o WhatsApp silencioso para DMs não autorizados — geralmente melhor para um número privado.

Em seguida, inicie o gateway:

hermes gateway              # Primeiro plano
hermes gateway install      # Instalar como serviço do usuário
sudo hermes gateway install --system   # Linux: serviço do sistema na inicialização

Persistência de Sessão e Reconexão

A ponte salva sua sessão em ~/.hermes/platforms/whatsapp/session. Isso significa que:

As sessões sobrevivem a reinicializações — sem precisar escanear novamente toda vez
Os dados da sessão incluem chaves de criptografia e credenciais do dispositivo
Não compartilhe nem faça commit deste diretório — ele concede acesso total à conta

Se a sessão quebrar (reset do celular, atualização do WhatsApp, desvinculação manual), você verá erros de conexão nos logs. Corrija executando:

hermes whatsapp

Isso gera um novo QR code para reconexão.

Essa é a nova configuração do WhatsApp em resumo. Rápida, leve e sem burocracia da Meta. No próximo artigo da série: vamos comparar esta ponte lado a lado com a WhatsApp Business Cloud API — fique ligado!