> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WAHA
> Decisão, arquitetura, capacidades, riscos e critérios para o primeiro provider não oficial de WhatsApp da Orquena.
# 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
```text theme={null}
Orquena API
↓
MessagingProvider
↓
WahaMessagingProvider
↓
WAHA node
↓
WhatsApp session
```
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:
| Engine | Perfil inicial |
| ------- | --------------------------------------------- |
| `WEBJS` | Compatibilidade e comportamento previsível |
| `WPP` | Alternativa browser-based a ser testada |
| `NOWEB` | Engine leve baseada em WebSocket |
| `GOWS` | Engine leve em Go para avaliação de densidade |
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
```text theme={null}
Webhook do WAHA
↓
Validação de assinatura
↓
Mapeamento interno da conexão resolve organizationId
↓
Persistência idempotente do evento bruto
↓
Resposta rápida ao provider
↓
Normalização assíncrona
↓
Inbox e eventos internos
```
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.
```text theme={null}
MessagingConnection
├── organizationId
├── provider: WAHA
├── providerNodeId
├── externalSessionId
├── engine
├── status
└── phoneNumber
```
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.
## Links oficiais
Visão geral, instalação e APIs.
Código, releases e licença.
Lifecycle e múltiplas sessões.
WEBJS, WPP, NOWEB e GOWS.
Webhooks e WebSockets.
API key e assinatura HMAC.