WhatsApp Business Mock (pt_BR)

Ferramenta open source para simular a WhatsApp Business Cloud API em desenvolvimento e testes locais, sem conta de produção na Meta.

Este repositório é 100% construído por IA, com curadoria e revisão humana.

Documentação em inglês (principal): README.md

O que inclui

• Backend NestJS com rotas no estilo oficial (/v1 e /v25.0)
• Painel admin em /admin
• Chat estilo WhatsApp Web em /chat
• SQLite (caminhos configuráveis)
• Execução via npx ou Docker

Início rápido

npx whatsapp-business-mock

O tarball publicado é enxuto: dist/ compilado + @whatsapp-business-mock/shared embutido (bundleDependencies). As demais dependências de runtime são instaladas pelo npm/npx na máquina do usuário. O prepublishOnly não inclui dist/node_modules. Para artefato autocontido (Docker), use npm run package:dist completo. Em um clone do git, use npm run package:dist antes de publicar ou npm run dev para desenvolvimento.

Com npx, abra http://localhost:3000/admin e http://localhost:3000/chat na mesma porta do servidor.

Docker (guia completo): docker/README.md

Imagem publicada (após configurar o workflow no GitHub):

docker pull caiquesportela/whatsapp-business-mock:latest
docker run -d --name wbm -p 3000:3000 -v wbm-data:/data \
  -e DB_PATH=/data/whatsapp-business-mock.db \
  -e STORAGE_PATH=/data/uploads \
  caiquesportela/whatsapp-business-mock:latest

Build a partir do repositório:

docker compose -f docker/docker-compose.yml up --build

• Admin: http://localhost:3000/admin
• Chat: http://localhost:3000/chat
• Swagger: http://localhost:3000/docs

Idioma da interface

en_US (padrão) e pt_BR no admin e no chat (seletor na interface; preferência em localStorage). A API e o Swagger permanecem em inglês.

Variáveis de ambiente

| Variável | Padrão | Descrição | |----------|--------|-----------| | PORT | 3000 | Porta HTTP | | DB_PATH | ./data/whatsapp-business-mock.db | SQLite | | STORAGE_PATH | ./data/uploads | Mídias | | BASE_URL | http://localhost:3000 | Links de mídia | | WHATSAPP_APP_SECRET ou APP_SECRET | vazio | Segredo do app: assina webhooks de saída e valida o endpoint de teste de entrada. Se vazio, a assinatura de saída é omitida e a verificação de entrada é ignorada (com aviso nos logs). |

Demais variáveis (SEED_*, LOG_LEVEL) — ver tabela completa no README.md.

Webhooks

• Entrega com cabeçalho X-Hub-Signature-256 = HMAC-SHA256 do corpo JSON bruto (quando o segredo está definido).
• Teste de POST com verificação: POST /local/webhook-config/receive/:phoneNumberId (corpo bruto + assinatura).

Chat

Rotas: /chat, /chat/:telefoneCliente, /chat/:telefoneCliente/:idConversa.

Com número WABA registrado, mensagens usam a API simulada. Sem WABA, use o modo peer (POST /local/conversations/peer-messages); abra o chat com o seu número na URL ou defina VITE_CLIENT_PHONE no build do front.

Desenvolvimento

npm install
npm run dev
npm test
npm run lint
npm run package:dist

Lançamento (GitHub Actions)

Fluxo sugerido: npm version patch && git push origin main --tags. Veja .github/workflows/release.yml e segredos NPM_TOKEN, DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.

Licença

MIT — LICENSE