Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Configuração do WhatsApp

O Hermes se conecta ao WhatsApp por uma ponte embutida baseada no Baileys. Ela funciona emulando uma sessão do WhatsApp Web — não usa a API oficial do WhatsApp Business. Não é preciso conta de desenvolvedor na Meta nem verificação de Business.

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

Duas integrações de WhatsApp

Esta página é sobre a ponte Baileys — rápida de configurar, funciona com contas pessoais, não precisa de URL pública, mas tem risco de banimento.

Se você vai rodar um bot de negócio de verdade e quer estabilidade, veja o guia da WhatsApp Business Cloud API. É o caminho oficial, com suporte da 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 com números de telefone diferentes, se você tiver motivo para isso.

API não oficial — risco de banimento

O WhatsApp não dá suporte oficial a bots de terceiros fora da Business API. Usar uma ponte de terceiros traz um pequeno risco de restrição da conta. Para minimizar o risco:

  • Use um número de telefone dedicado ao bot (não o seu número pessoal)
  • Não envie mensagens em massa nem spam — mantenha o uso conversacional
  • Não automatize mensagens de saída para pessoas que não escreveram primeiro
Atualizações do protocolo do WhatsApp Web

O WhatsApp atualiza o protocolo Web de tempos em tempos, o que pode quebrar temporariamente a compatibilidade com pontes de terceiros. Quando isso acontece, o Hermes atualiza a dependência da ponte. Se o bot parar de funcionar depois de uma atualização do WhatsApp, atualize para a versão mais recente do Hermes e refaça o pareamento.

Dois modos​

ModoComo funcionaMelhor para
Número separado para o bot (recomendado)Dedique um número de telefone ao bot. As pessoas escrevem direto para esse número.Experiência limpa, vários usuários, menor risco de banimento
Autoconversa pessoalUse o seu próprio WhatsApp. Você manda mensagem para si mesmo para falar com o agente.Configuração rápida, um único usuário, testes

Pré-requisitos​

  • 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)

Diferente das pontes antigas baseadas em navegador, a ponte atual, baseada em Baileys, não exige uma pilha local de Chromium ou Puppeteer.

Passo 1: rode o assistente de configuração​

hermes whatsapp

O assistente vai:

  1. Perguntar qual modo você quer (bot ou self-chat)
  2. Instalar as dependências da ponte, se preciso
  3. Exibir um QR code no seu terminal
  4. Esperar você escanear

Para escanear o QR code:

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

Depois de pareado, o assistente confirma a conexão e sai. Sua sessão é salva automaticamente.

dica

Se o QR code aparecer embaralhado, verifique se o seu terminal tem pelo menos 60 colunas de largura e suporta Unicode. Você também pode tentar outro emulador de terminal.

Passo 2: conseguir um segundo número de telefone (modo bot)​

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

OpçãoCustoObservações
Google VoiceGrátisSó nos EUA. Consiga um número em voice.google.com. Verifique o WhatsApp por SMS pelo app do Google Voice.
Chip pré-pagoUS$ 5–15 uma vezQualquer operadora. Ative, verifique no WhatsApp e depois o chip pode ficar guardado na gaveta. O número precisa continuar ativo (faça uma ligação a cada 90 dias).
Serviços VoIPGrátis–US$ 5/mêsTextNow, TextFree ou similares. Alguns números VoIP são bloqueados pelo WhatsApp — teste alguns se o primeiro não funcionar.

Depois de conseguir o número:

  1. Instale o WhatsApp em um celular (ou use o app WhatsApp Business com dois chips)
  2. Registre o novo número no WhatsApp
  3. Rode hermes whatsapp e escaneie o QR code por essa conta do WhatsApp

Passo 3: configure o Hermes​

Acrescente 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 separados por vírgula (com código do país, sem +)
# WHATSAPP_ALLOWED_USERS=*                 # OU use * para liberar para todo mundo
# WHATSAPP_ALLOW_ALL_USERS=true            # OU defina esta flag (mesmo efeito do *)
Atalho para liberar todo mundo

Definir WHATSAPP_ALLOWED_USERS=* libera todos os remetentes (equivale a WHATSAPP_ALLOW_ALL_USERS=true). Isso é consistente com as listas de permissão de grupo do Signal. Para usar o fluxo de pareamento no lugar disso, remova as duas variáveis e conte com o 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 ficar em silêncio diante de DMs não autorizadas, o que costuma ser a melhor escolha para um número privado.

Depois, suba o gateway:

hermes gateway              # Em primeiro plano
hermes gateway install      # Instala como serviço de usuário
sudo hermes gateway install --system   # Só Linux: serviço de sistema iniciado no boot

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

Persistência da sessão​

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

  • As sessões sobrevivem a reinicializações — você não precisa escanear o QR code toda vez
  • Os dados da sessão incluem chaves de criptografia e credenciais do dispositivo
  • Não compartilhe nem versione esse diretório de sessão — ele dá acesso total à conta do WhatsApp

Refazer o pareamento​

Se a sessão quebrar (celular resetado, atualização do WhatsApp, desconexão manual), você vai ver erros de conexão nos logs do gateway. Para resolver:

hermes whatsapp

Isso gera um QR code novo. Escaneie de novo e a sessão é restabelecida. O gateway trata desconexões temporárias (oscilações de rede, celular offline por pouco tempo) automaticamente, com lógica de reconexão.

Mensagens de voz​

O Hermes tem suporte a voz no WhatsApp:

  • Entrada: mensagens de voz (.ogg opus) são transcritas automaticamente pelo provedor de STT configurado: faster-whisper local, Groq Whisper (GROQ_API_KEY) ou OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
  • Saída: respostas em TTS são enviadas como anexos de áudio MP3
  • As respostas do agente vêm com o prefixo "⚕ Hermes Agent" por padrão. Dá para personalizar ou desativar isso no config.yaml:
# ~/.hermes/config.yaml
whatsapp:
  reply_prefix: ""                          # String vazia desativa o cabeçalho
  # reply_prefix: "🤖 *Meu Bot*\n──────\n"  # Prefixo próprio (aceita \n para quebra de linha)
  send_read_receipts: false                 # Marca como lidas as mensagens de entrada aceitas (tiques azuis)

Quando send_read_receipts é true, o adaptador marca como lidas as mensagens de entrada aceitas pela política, depois de passar pelos filtros de DM/grupo/menção. Mensagens rejeitadas (por exemplo, de remetentes fora da lista de permissão) não são marcadas como lidas. Desativado por padrão, por privacidade. Alterar essa configuração reinicia automaticamente o subprocesso da ponte na próxima conexão.

Formatação e entrega das mensagens​

O WhatsApp suporta respostas em streaming (progressivas) — o bot edita a mensagem em tempo real conforme a IA gera o texto, igual ao Discord e ao Telegram. Internamente, o WhatsApp é classificado como plataforma TIER_MEDIUM em capacidade de entrega.

Fatiamento​

Respostas longas são divididas automaticamente em várias mensagens a cada 4.096 caracteres por pedaço (o limite prático de exibição do WhatsApp). Você não precisa configurar nada — o gateway cuida da divisão e envia os pedaços em sequência.

Markdown compatível com o WhatsApp​

O Markdown padrão das respostas da IA é convertido automaticamente para a formatação nativa do WhatsApp:

MarkdownWhatsAppAparece como
**bold***bold*negrito
~~strikethrough~~~strikethrough~tachado
# Heading*Heading*Texto em negrito (não há títulos nativos)
[link text](url)link text (url)URL inline

Blocos de código e código inline são preservados como estão, já que o WhatsApp suporta a formatação com três crases nativamente.

Progresso das ferramentas​

Quando o agente chama ferramentas (busca na web, operações de arquivo etc.), o WhatsApp exibe indicadores de progresso em tempo real mostrando qual ferramenta está rodando. Isso vem ativado por padrão — sem configuração.

Enquetes nativas, esclarecimento como enquete e localizações​

O adaptador da ponte Baileys (modo bot) suporta vários tipos nativos de mensagem do WhatsApp:

  • Enquetes — o agente pode enviar uma enquete nativa do WhatsApp (pergunta + opções) pelo endpoint /send-poll da ponte. Os votos voltam para a conversa.
  • Perguntas de esclarecimento como enquete — quando o agente faz uma pergunta de esclarecimento de múltipla escolha, ela é renderizada como uma enquete nativa de escolha única; tocar em uma opção responde a pergunta. Se a enquete falhar no envio, o adaptador cai para uma pergunta em texto puro. Pedidos de aprovação nunca são mapeados para enquetes — enquetes só são usadas em esclarecimentos genuínos de múltipla escolha.
  • Marcadores de localização — o agente pode enviar um marcador de localização nativo (latitude/longitude, com nome/endereço opcionais) pelo /send-location, e as localizações compartilhadas recebidas (incluindo localização em tempo real) chegam ao agente como mensagens de localização.

Tudo isso funciona de imediato no modo bot (Baileys); nenhuma configuração é necessária.

Agrupamento de mensagens (debounce)​

O WhatsApp entrega cada mensagem individualmente, então uma rajada rápida (encaminhamentos em lote, colagens quebradas, texto em várias linhas) dispararia uma invocação de agente por fragmento — desperdiçando tokens e produzindo várias respostas desconexas. O adaptador acumula mensagens de texto sucessivas do mesmo chat e as despacha como uma única requisição combinada após um curto período de silêncio (padrão 5s, estendido para 10s em fragmentos muito longos). Ajuste pelo config.yaml:

# ~/.hermes/config.yaml
gateway:
  platforms:
    whatsapp:
      extra:
        text_batch_delay_seconds: 5.0         # silêncio antes de despachar o lote
        text_batch_split_delay_seconds: 10.0  # atraso estendido perto do limiar de divisão

Defina text_batch_delay_seconds: 0 para despachar cada mensagem na hora (desativa o agrupamento).

Resolução de problemas​

ProblemaSolução
QR code não escaneiaGaranta que o terminal seja largo o bastante (60+ colunas). Tente outro terminal. Confirme que você está escaneando pela conta certa do WhatsApp (o número do bot, não o pessoal).
QR code expiraOs QR codes se renovam a cada ~20 segundos. Se estourar o tempo, rode hermes whatsapp de novo.
Sessão não persisteVerifique se ~/.hermes/platforms/whatsapp/session existe e tem permissão de escrita. Em container, monte como volume persistente.
Deslogado sem avisoO WhatsApp desconecta dispositivos depois de longa inatividade. Mantenha o celular ligado e conectado à rede e, se preciso, refaça o pareamento com hermes whatsapp.
Ponte quebra ou entra em laço de reconexãoReinicie o gateway, atualize o Hermes e refaça o pareamento se a sessão foi invalidada por uma mudança de protocolo do WhatsApp.
Bot para de funcionar depois de uma atualização do WhatsAppAtualize o Hermes para pegar a versão mais recente da ponte e refaça o pareamento.
macOS: "Node.js not installed", mas o node funciona no terminalServiços do launchd não herdam o PATH do seu shell. Rode hermes gateway install para capturar de novo o PATH atual no plist e depois hermes gateway start. Veja a documentação do serviço de gateway para detalhes.
Mensagens não chegamConfira se WHATSAPP_ALLOWED_USERS inclui o número do remetente (com código do país, sem + nem espaços), ou defina como * para liberar todo mundo. Coloque WHATSAPP_DEBUG=true no .env e reinicie o gateway para ver os eventos brutos de mensagem no bridge.log.
O bot responde a desconhecidos com um código de pareamentoDefina whatsapp.unauthorized_dm_behavior: ignore no ~/.hermes/config.yaml se preferir que DMs não autorizadas sejam ignoradas em silêncio.

Segurança​

aviso

Configure o controle de acesso antes de entrar em produção. Defina WHATSAPP_ALLOWED_USERS com números de telefone específicos (com código do país, sem o +), use * para liberar todo mundo ou defina WHATSAPP_ALLOW_ALL_USERS=true. Sem nenhuma dessas opções, o gateway nega todas as mensagens de entrada por segurança.

Por padrão, DMs não autorizadas ainda recebem uma resposta com código de pareamento. Se você quer que um número privado do WhatsApp fique completamente em silêncio para desconhecidos, defina:

whatsapp:
  unauthorized_dm_behavior: ignore
  • O diretório ~/.hermes/platforms/whatsapp/session contém as credenciais completas da sessão — proteja como se fosse uma senha
  • Ajuste as permissões do arquivo: chmod 700 ~/.hermes/platforms/whatsapp/session
  • Use um número de telefone dedicado ao bot para isolar o risco da sua conta pessoal
  • Se suspeitar de comprometimento, desconecte o dispositivo no WhatsApp → Configurações → Aparelhos conectados
  • Números de telefone nos logs são parcialmente ocultados, mas revise sua política de retenção de logs