Skip to main content

​
WhatsApp com WAHA

O primeiro provider não oficial de WhatsApp da Orquena será o WAHA — WhatsApp HTTP API.
O WAHA será utilizado para desenvolvimento, testes e pilotos controlados. Ele não é a API oficial da Meta e não elimina riscos de desconexão, bloqueio ou mudanças incompatíveis no WhatsApp.

​
Por que o WAHA foi escolhido

A partir da distribuição 2026.6.1, recursos anteriormente associados ao WAHA Plus foram incorporados à imagem pública Core. O projeto atualmente documenta:
  • Sessões sem limite imposto pelo plano Core.
  • Mensagens de texto e mídia.
  • Persistência de sessões.
  • API HTTP, webhooks e WebSockets.
  • API key e assinatura HMAC de webhooks.
  • Health checks, métricas e observabilidade.
  • Diferentes engines de conexão.
Isso o torna adequado para construir e validar a abstração de mensageria da Orquena sem começar pela complexidade comercial da Meta Cloud API.

​
Posição na arquitetura

WAHA é infraestrutura substituível. Scheduling, CRM, Inbox e AI Runtime não podem chamar seus endpoints diretamente.

​
Estratégia de engines

O WAHA oferece engines com características diferentes: A primeira implementação começa com WEBJS. NOWEB e GOWS só poderão receber tráfego após passarem pela mesma suíte de contratos, mídia, reconexão e webhooks.
Uma API semelhante entre engines não garante paridade perfeita de payloads, eventos ou recursos. Toda diferença deve ser normalizada dentro do provider.

​
Responsabilidades do provider

  • Criar, iniciar, parar, reiniciar e remover sessões.
  • Recuperar QR Code, pairing code e estado da conexão.
  • Enviar texto e mídia.
  • Validar e normalizar webhooks.
  • Normalizar contatos, mensagens, acknowledgements e erros.
  • Associar sessão a organização, conexão e node.
  • Aplicar timeout, retry, circuit breaker e métricas.
  • Impedir duplicidade por identificador externo.
  • Registrar engine e versão da conexão.

​
Webhooks

Um campo de tenant recebido no payload externo nunca é autoridade. A geração de resposta por IA nunca bloqueia a confirmação do webhook.

​
Multi-tenancy

Toda sessão pertence a uma organização. No piloto inicial, cada tenant usa um número de WhatsApp Business principal próprio. O nome enviado ao WAHA será um identificador opaco, sem nome de cliente, email ou tenant previsível.
Organizações pertencentes à mesma conta comercial continuam com sessões, contatos, conversas e permissões independentes.

​
O que significa “sessões ilimitadas”

O WAHA Core não aplica um limite comercial fixo de sessões. Isso não significa recursos físicos ilimitados. A capacidade real depende de:
  • Engine selecionada.
  • Processos de browser.
  • Memória e CPU.
  • Volume de mídia.
  • Reconexões.
  • Taxa de mensagens.
  • Comportamento do WhatsApp.
A Orquena publicará somente números comprovados por teste de carga e recuperação.

​
Principais riscos

  • Não é uma integração oficial da Meta.
  • Mudanças no WhatsApp podem quebrar uma engine.
  • Contas podem exigir novo pareamento.
  • Automação abusiva pode resultar em restrições.
  • Sessões e mídia exigem persistência e backup adequados.
Controles obrigatórios:
  • Números de teste dedicados.
  • Aumento gradual de tráfego.
  • Kill switch por organização e conexão.
  • Limites conservadores.
  • Métricas de desconexão e reconexão.
  • Divulgação clara do tipo de integração.
  • Campanhas em massa desabilitadas no beta.

​
Comparação com Evolution API

Evolution API continuará na lista de observação, mas não será o primeiro provider. Sua versão 2.4.0 introduziu ativação obrigatória de instância por um serviço externo antes do uso dos endpoints de negócio. A Orquena prefere, neste momento, o fluxo Core gratuito do WAHA para experimentação.

​
Critérios antes de um piloto

  • Suíte de contrato aprovada para a engine escolhida.
  • Sessão recuperada após reinício do container.
  • Webhook duplicado não gera mensagem ou resposta duplicada.
  • HMAC e API key ativados.
  • Limites de mídia configurados.
  • Métricas de estado, erro e latência disponíveis.
  • Procedimento de drain e recuperação do node documentado.
  • Kill switch testado.
  • Teste prova que um tenant não acessa a sessão de outro tenant da mesma conta.

​
Futuro oficial

A abstração permitirá adicionar a Meta Cloud API sem reescrever Inbox, CRM, agenda ou agentes.

Documentação do WAHA

Visão geral, instalação e APIs.

Repositório

Código, releases e licença.

Sessões

Lifecycle e múltiplas sessões.

Engines

WEBJS, WPP, NOWEB e GOWS.

Eventos

Webhooks e WebSockets.

Segurança

API key e assinatura HMAC.