WhatsApp — IA para o Chat Mais Usado do Mundo

O WhatsApp está em todo lugar. Mais de dois bilhões de pessoas o usam diariamente, e agora você pode conectar o Hermes diretamente nele. Sem conta de desenvolvedor Meta. Sem verificação de negócios. Sem configuração complicada de API. Apenas um scan de QR code e você já está falando com seu agente de IA pelo mesmo app que você usa para conversar com seus amigos.

Como Funciona

O Hermes se conecta ao WhatsApp através de uma ponte integrada baseada em Baileys. Pense nisso como uma emulação de sessão do WhatsApp Web — da mesma forma que você vincularia um navegador ao seu celular. Não é a API oficial do WhatsApp Business, o que significa que você não precisa de nenhuma aprovação especial para começar.

Execute hermes gateway setup e escolha WhatsApp para um passo a passo guiado.

Duas Formas de Usar

Modo	Como funciona	Melhor para
Número de bot separado (recomendado)	Dedique um número de telefone ao bot. As pessoas enviam mensagens diretamente para esse número.	UX limpa, múltiplos usuários, menor risco de banimento
Self-chat pessoal	Use seu próprio WhatsApp. Você envia mensagem para si mesmo para falar com o agente.	Configuração rápida, usuário único, testes

A abordagem com número de bot separado é mais limpa — sua IA tem identidade própria, e você não mistura conversas pessoais com conversas do bot. O modo self-chat é perfeito para um teste rápido.

Antes de Começar

Você vai precisar de:

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

Boas notícias: diferente de pontes antigas baseadas em navegador, você não precisa de Chromium ou Puppeteer instalados. A configuração é muito mais leve.

Passo 1: Execute o Assistente de Configuração

hermes whatsapp

O assistente vai:

Perguntar qual modo você quer (bot ou self-chat)
Instalar 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 o pareamento, 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. Você também pode tentar um emulador de terminal diferente.

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

Para o modo bot, você precisa de um número que ainda não esteja registrado no WhatsApp. Aqui estão suas opções:

Opção	Custo	Observações
Google Voice	Grátis	Somente EUA. Obtenha um número em voice.google.com. Verifique o WhatsApp via SMS pelo app do Google Voice.
SIM pré-pago	US$ 5–15 pagamento único	Qualquer operadora. Ative, verifique o WhatsApp, e o SIM pode ficar guardado numa gaveta. O número precisa permanecer ativo (faça uma chamada a cada 90 dias).
Serviços VoIP	Grátis–US$ 5/mês	TextNow, TextFree ou similares. Alguns números VoIP são bloqueados pelo WhatsApp — tente alguns se o primeiro não funcionar.

Depois de obter o número:

Instale o WhatsApp em um celular (ou use o app WhatsApp Business com SIM duplo)
Registre o novo número no WhatsApp
Execute hermes whatsapp e escaneie o QR code dessa conta do WhatsApp

Passo 3: Configure o Hermes

Adicione o seguinte ao seu arquivo ~/.hermes/.env:

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

# Controle de acesso — escolha UMA destas opções:
WHATSAPP_ALLOWED_USERS=15551234567         # Números de telefone separados por vírgula (com código do país, sem +)
# WHATSAPP_ALLOWED_USERS=*                 # OU use * para permitir todos
# WHATSAPP_ALLOW_ALL_USERS=true            # OU defina esta flag (mesmo efeito que *)

Atalho para permitir todos: Definir WHATSAPP_ALLOWED_USERS=* permite todos os remetentes. Para usar o fluxo de pareamento, remova ambas as variáveis e dependa do sistema de pareamento por DM.

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

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

unauthorized_dm_behavior: pair é o padrão global. Remetentes desconhecidos de DM recebem um código de pareamento.
whatsapp.unauthorized_dm_behavior: ignore faz o WhatsApp permanecer em silêncio para DMs não autorizadas — geralmente a melhor escolha para um número privado.

Depois, inicie o gateway:

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

O gateway inicia a ponte do WhatsApp automaticamente usando a sessão salva.

Persistência de Sessão

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

Sessões sobrevivem a reinicializações — você não precisa escanear o QR code 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 de sessão — ele concede acesso total à conta do WhatsApp

Repareamento

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

hermes whatsapp

Isso gera um novo QR code para repareamento.

Um Alerta

O WhatsApp não suporta oficialmente bots de terceiros fora da Business API. Usar uma ponte de terceiros carrega um pequeno risco de restrições na conta. Para minimizar o risco:

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

Além disso, o WhatsApp atualiza periodicamente seu protocolo Web, o que pode quebrar temporariamente a compatibilidade com pontes de terceiros. Quando isso acontecer, o Hermes atualizará a dependência da ponte. Se o bot parar de funcionar após uma atualização do WhatsApp, baixe a versão mais recente do Hermes e faça o repareamento.

Quer Algo Mais Oficial?

Se você está rodando um bot de negócios de verdade e quer estabilidade, confira o guia da WhatsApp Business Cloud API. É o caminho oficial suportado pela Meta: sem risco de banimento da conta, mas exige uma conta Meta Business e uma URL pública de webhook. Os dois adaptadores também podem rodar em paralelo contra números de telefone diferentes, se você tiver um motivo para isso.

Para a maioria dos projetos pessoais e experimentos, porém, a ponte Baileys é o caminho mais rápido para colocar IA no seu WhatsApp. Escaneie, configure e comece a conversar.