Sistema organizacional de disparo em massa no WhatsApp com confiança e credibilidade, construído sobre o uso primário da API Oficial do WhatsApp (Meta Cloud API) e desenhado para ser replicado.
Criado e mantido por Luiz Henrique (@luizxhgomes)
O WhatsFlow Engine é um SaaS single-tenant completo de automação de marketing e atendimento no WhatsApp. Ele resolve o problema central do disparo em massa: fazer campanhas em escala sem queimar o número, sem banimento e sem gambiarras, porque toda a comunicação passa exclusivamente pela API Oficial do WhatsApp (Meta Cloud API), nunca por bibliotecas não-oficiais de engenharia reversa.
O que o torna interessante como referência de construção de sistema é a orquestração ponta a ponta: fila durável com QStash, throttling adaptativo por qualidade de número, templates aprovados pela Meta, rastreio de status por mensagem (enviada, entregue, lida, falhou) e um workflow builder visual para jornadas conversacionais. A camada de IA (Vercel AI SDK v6, multi-provider) responde conversas no inbox com memória persistente.
A qualidade é garantida por mais de 3.500 testes (Vitest + Playwright), lint estrito e CI. A arquitetura segue um padrão único e auditável em todas as features: Page → Hook → Service → API Route.
O sistema foi desenhado para ser replicado: um installer automático provisiona Supabase e Vercel, e o guia de setup cobre do app da Meta ao deploy.
git clone https://github.com/luizxhgomes/whatsflow-engine.git
cd whatsflow-engine/app
cp .env.example .env # preencha as credenciais
npm install && npm run dev| Pilar | Como o engine implementa |
|---|---|
| Zero engenharia reversa | 100% Meta Cloud API. Sem Baileys, sem web-scraping, sem risco de ban por protocolo. |
| Templates aprovados | Ciclo completo de criação, submissão e aprovação de templates HSM direto pela Meta. |
| Qualidade de número | Throttling adaptativo (WHATSAPP_ADAPTIVE_*): a taxa de envio reage ao rating de qualidade do número. |
| Opt-in e rastreabilidade | Contatos com origem rastreada, import CSV validado, status por mensagem via webhooks assinados (HMAC). |
| Rate limits respeitados | Fila durável QStash com concorrência configurável e retry com backoff. |
%%{init: {'theme':'base','themeVariables':{
'background':'#0B141A','primaryColor':'#0F2620','primaryTextColor':'#E9EDEF',
'primaryBorderColor':'#25D366','lineColor':'#00A884','secondaryColor':'#075E54',
'tertiaryColor':'#111B21','fontSize':'15px','edgeLabelBackground':'#0B141A',
'clusterBkg':'#111B21','clusterBorder':'#128C7E'}}}%%
flowchart LR
subgraph ORQ[" Orquestração "]
A["Campanha<br/>criada"] --> B["Fila durável<br/>QStash"]
W["Flows: jornadas<br/>automatizadas<br/>(workflow builder)"] --> B
B --> C{"Throttling<br/>adaptativo"}
end
subgraph ENV[" Envio pela API Oficial "]
C --> D["Meta Cloud API"]
D --> E["WhatsApp<br/>do contato"]
end
subgraph FBK[" Feedback loop "]
D --> F["Webhook de status<br/>assinado HMAC"]
F --> R[("Redis: memória quente<br/>dedup de eventos ·<br/>última mensagem ·<br/>cache de settings")]
R --> G[("Supabase<br/>fonte da verdade")]
G --> H["Métricas por mensagem<br/>enviada · entregue · lida · falhou"]
end
E -.->|"resposta do contato (inbound)"| W
H -.->|"qualidade do número regula a taxa"| C
style A fill:#111B21,stroke:#128C7E,color:#E9EDEF
style B fill:#0F2620,stroke:#25D366,color:#E9EDEF
style C fill:#075E54,stroke:#57D163,color:#FFFFFF
style W fill:#075E54,stroke:#57D163,color:#FFFFFF
style D fill:#128C7E,stroke:#57D163,color:#FFFFFF
style E fill:#0F2620,stroke:#25D366,color:#D9FDD3
style R fill:#111B21,stroke:#00A884,color:#E9EDEF
style F fill:#111B21,stroke:#00A884,color:#E9EDEF
style G fill:#111B21,stroke:#00A884,color:#E9EDEF
style H fill:#0F2620,stroke:#25D366,color:#D9FDD3
Três engrenagens sustentam o desenho:
- Laço de credibilidade (tracejado inferior): as métricas de qualidade do número realimentam o throttling, o sistema desacelera sozinho antes de comprometer a reputação do número.
- Memória quente no Redis: cada evento de webhook passa pelo dedup (
SET NXcom TTL), a última mensagem de cada conversa fica emai:lastmsg:*para o debounce da IA responder com contexto fresco, e as settings ganham cache com TTL. O Supabase permanece a fonte da verdade; o Redis é a camada de velocidade. - Flows (jornadas automatizadas): o workflow builder visual (React Flow) constrói jornadas que reagem à resposta do contato (inbound) e reentram na fila de envio, com estado de conversa persistido em
workflow_conversations.
Padrão de código em todas as features:
Page (App Router) → Hook (estado/TanStack Query) → Service (regra de negócio) → API Route (integração)
whatsflow-engine/
├── app/ # o sistema (Next.js 16)
│ ├── app/ # 34 páginas + 217 rotas de API
│ ├── components/ hooks/ services/ lib/ # camadas (ver abaixo)
│ ├── supabase/migrations/ # schema (35+ tabelas, 7 domínios)
│ └── infra/ # Docker, VPS, deploy
└── docs/
├── architecture/ # ADRs + TOPOLOGIA.md (documento único de topologia)
├── setup/ # replicação passo a passo
└── prd/ epics/ stories/ # metodologia story-driven
Topologia completa (física, lógica, execução, dados e replicação):
docs/architecture/TOPOLOGIA.md
| Componente | Quantidade |
|---|---|
| Rotas de API | 217 |
| Páginas (App Router) | 34 |
| Componentes React | 444 |
| Hooks | 61 |
| Migrations Supabase | 10 |
| Arquivos de teste | 114 (3.500+ testes) |
Funcionalidades: inbox de atendimento com visual WhatsApp Business, campanhas em massa com métricas, contatos + import CSV, templates HSM com preview fiel, workflow builder visual (React Flow), installer automático (Supabase + Vercel), diagnóstico da integração Meta, push notifications, IA multi-provider com memória.
Next.js 16 (App Router, Turbopack) · React 19 · TypeScript 5.7 · Supabase (Postgres + Auth + Storage) · Upstash QStash + Redis · Meta WhatsApp Cloud API · Vercel AI SDK v6 (Anthropic, OpenAI, Google) · Tailwind 4 + Radix/shadcn · Vitest + Playwright.
- Supabase: crie um projeto e rode as migrations de
app/supabase/migrations/. - Meta: crie um app WhatsApp Business, conecte o WABA, gere token permanente e configure o webhook (guia em
docs/setup/). - Upstash: crie o QStash e o Redis, copie tokens.
- Variáveis:
cp app/.env.example app/.enve preencha. - Deploy: Vercel (recomendado) ou Docker/VPS (
app/infra/). O installer embutido (/api/installer) automatiza o provisionamento.
Guias completos: docs/setup/README.md · docs/guides/ · app/infra/DEPLOY-GUIDE.md
Três documentos sustentam o lema do sistema, escritos a partir de auditoria do código real:
docs/seguranca/GARANTIAS-ANTI-BLOQUEIO.md: playbook preventivo contra bloqueios da Meta (opt-in, aquecimento, tiers, throttling por qualidade, LGPD) com checklist pré-campanha.docs/seguranca/GARANTIAS-DE-ENTREGA.md: o que o sistema garante no disparo (HMAC, dedup, fila, retry, status por mensagem) e como testar cada garantia.docs/seguranca/CONTRATO-API-OFICIAL.md: mapa das correspondências com a Meta Cloud API: tipos de mensagem, janela de 24 horas e códigos de erro.
A jornada completa de implantação white-label vive em docs/onboarding/: 5 fases com gates verificáveis, do install à operação contínua, mais o roadmap estratégico priorizado.
Desenvolvimento story-driven: PRD → epics → stories com acceptance criteria → implementação → QA gate. Os artefatos reais estão versionados em docs/prd/, docs/epics/ e docs/stories/ como registro do método.
- Somente API Oficial da Meta, nenhuma dependência de protocolo não-oficial.
- Nenhum segredo no repositório, tudo via variáveis de ambiente (
.env.exampledocumenta o contrato). - Disparo responsável, throttling, opt-in e templates aprovados não são opcionais.
- Todo código novo entra com teste.
Veja CONTRIBUTING.md. Issues e PRs são bem-vindos.
MIT. WhatsApp e Meta são marcas de seus respectivos donos; este projeto não representa afiliação oficial com a Meta.
Luiz Henrique, engenharia de sistemas de IA e automação · @luizxhgomes