Open Source WhatsApp Business API Gateway
Multi-engine • Self-hosted • Enterprise-ready

Quick Start • Features • Screenshots • Architecture • API Docs • SDKs • Deployment • Release Checks • Contributing

MultiWA is a fully self-hosted, open-source WhatsApp API gateway that lets you connect multiple WhatsApp numbers through a single unified REST + WebSocket API. It runs as a docker compose up stack on your own server, ships an admin dashboard for QR onboarding and live chat, and exposes official SDKs for TypeScript, Python, and PHP.

If you want to send and receive WhatsApp messages from your own backend without per-message pricing, vendor lock-in, or sending customer data through a third party, MultiWA is built for you.

⭐ If you find MultiWA useful, please consider giving it a star!
It helps us grow and motivates continued development.

git clone https://github.com/ribato22/MultiWA.git
cd MultiWA
cp .env.docker .env
docker compose up -d

That's it! Access:

• 🖥️ Admin Dashboard: http://localhost:3001
• 📖 API Swagger Docs: http://localhost:3333/api/docs
• 🔌 API Endpoint: http://localhost:3333/api/v1

Full stack (with S3 storage + Nginx proxy): docker compose --profile full up -d

📦 Published SDK packages, signed container images, and a one-click Render deploy are rolling out — see Releasing & Distribution.

Prerequisites: Node.js ≥ 20 · PostgreSQL ≥ 16 · Redis ≥ 7 · pnpm ≥ 9

git clone https://github.com/ribato22/MultiWA.git
cd MultiWA
pnpm install

cp .env.example .env

# Setup database (no migrations dir — db push syncs the schema)
pnpm --filter database exec prisma generate
pnpm --filter database exec prisma db push

# Build workspace packages
pnpm --filter database build
pnpm --filter engines build

# Start development
pnpm --filter api dev     # API on http://localhost:3000
pnpm --filter admin dev   # Admin on http://localhost:3001

• 📱 Multi-Session Management — Connect unlimited WhatsApp accounts
• 🔌 Pluggable Engine Adapters — Clean engine interface with per-profile engine selection: whatsapp-web.js (default, production) or a Baileys adapter (experimental — not production-validated; sendReaction and resolveIdentity are stubs and history sync / WhatsApp-addressbook contact save are whatsapp-web.js-only; see Engine Abstraction)
• 📨 Unified Messaging API — Send text, media, documents, contacts, locations
• 📡 Real-time WebSocket — Live session status, QR codes, and events via Socket.IO
• 🔐 JWT Authentication — Secure API access with refresh tokens

• 🖥️ Modern UI — Next.js 14 with dark mode, responsive design
• 💬 Live Chat — Real-time chat interface with message history
• 📊 Analytics — Message volume, delivery rates, session metrics
• 🔍 Audit Trail — Complete logging of all operations

• 🤖 Visual Flow Builder — Drag & drop automation design
• 🧠 Knowledge Base — AI-powered replies using OpenAI (or any OpenAI-compatible API) with keyword (TF-IDF) retrieval
• 📅 Scheduled Messages — Queue messages for future delivery
• 📢 Broadcast — Bulk messaging with templates and tracking

• 🔗 Webhooks — Real-time event notifications to your services
• 🔑 API Keys — Multiple keys with scoping and expiration
• 📦 SDKs — TypeScript, Python, PHP
• 🔔 Push Notifications — Browser push via Web Push API
• 📧 SMTP Email — Email alerts for critical events

• 🛡️ Security — Helmet, CSP, rate limiting, encryption at rest
• 🐳 Docker — Production-ready containers with health checks
• 📈 Metrics — Prometheus /metrics (API, root path) + /metrics on the worker health port: default Node/process metrics plus BullMQ queue depth. Public like /health — restrict at your proxy/firewall
• ⚙️ Background Worker — BullMQ worker scaffolding (a durable async send queue is on the roadmap; today message sending and scheduling run in the API process)
• 🔒 GDPR — Data export and deletion endpoints
• 🔌 Plugin System — Extend with custom plugins

View all screenshots →

┌──────────────────────────────────────────────────────────┐
│                    Nginx (SSL / Proxy)                   │
├──────────────────────┬───────────────────────────────────┤
│  Admin (Next.js)     │  API (NestJS / Fastify)           │
│  Port 3001           │  Port 3333 (Docker)               │
│                      │  Port 3000 (local dev)            │
│                      │  ├─ /api/v1  REST + Swagger UI    │
│                      │  └─ /socket.io  realtime events   │
│                      ├───────────────────────────────────┤
│                      │  WhatsApp Engine Adapters         │
│                      │  ├─ whatsapp-web.js               │
│                      │  └─ Baileys (experimental)        │
├──────────────────────┴───────────────────────────────────┤
│  Worker (BullMQ)  │  PostgreSQL 16  │  Redis 7           │
└──────────────────────────────────────────────────────────┘

Full interactive API documentation is available at /api/docs (Swagger UI).

curl -X POST http://localhost:3333/api/v1/messages/text \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "profile-uuid",
    "to": "6281234567890",
    "text": "Hello from MultiWA! 👋"
  }'

curl -X POST http://localhost:3333/api/v1/accounts/YOUR_ACCOUNT_ID/profiles/YOUR_PROFILE_ID/connect \
  -H "Authorization: Bearer YOUR_TOKEN"

📚 See the full documentation site for detailed guides, API reference, webhook events, and more. Source docs are in the docs/ directory.

Official SDKs are included in the repository today. Registry publishing (NPM, PyPI, Packagist) is tracked as a release follow-up — until those registries are verified, install from this repo or via the local workspace path.

import { MultiWAClient } from '@multiwa/sdk';

const client = new MultiWAClient({
  // Docker default: 'http://localhost:3333/api/v1'
  // Local dev default if you omit baseUrl: 'http://localhost:3000/api/v1'
  baseUrl: 'http://localhost:3333/api/v1',
  apiKey: 'your-api-key',
});

// Send a text message
await client.messages.sendText({
  profileId: 'profile-uuid',
  to: '6281234567890',
  text: 'Hello! 👋',
});

MultiWA/
├── apps/
│   ├── api/             # NestJS backend API
│   ├── admin/           # Next.js admin dashboard
│   └── worker/          # BullMQ background worker
├── packages/
│   ├── core/            # Shared types and utilities
│   ├── database/        # Prisma schema and migrations
│   ├── engines/         # WhatsApp engine adapters
│   ├── sdk/             # TypeScript SDK (`@multiwa/sdk`)
│   ├── sdk-python/      # Python SDK (`multiwa`)
│   └── sdk-php/         # PHP SDK (`multiwa/multiwa-php`)
├── plugins/             # Plugin directory
├── docker/              # Dockerfiles (api, admin, worker)
├── docs/                # Public documentation
├── scripts/             # Release-gate scripts and utilities
└── .github/workflows/   # CI, release-gate, docker-publish, docs-deploy

Detailed deployment guide: docs/16-deployment-docker.md

# 1. Clone and configure
git clone https://github.com/ribato22/MultiWA.git
cd MultiWA
cp .env.production.example .env
# Edit .env with your settings (JWT_SECRET, DB_PASSWORD, etc.)

# 2. Build and start (with all optional services)
docker compose --profile full up -d --build

# 3. Sync the database schema (the API container also does this automatically
#    on startup; run manually only if you need to force it)
docker exec multiwa-api npx prisma db push --schema=packages/database/prisma/schema.prisma

# 4. Access
# API:    http://your-server:3333/api/docs
# Admin:  http://your-server:3001

💡 For advanced production setups (custom Nginx, external PostgreSQL, SSL), see the docker-compose.production.yml which is optimized for enterprise deployments with pre-configured Nginx reverse proxy.

Every push to main and every pull request runs the Release Gate workflow at .github/workflows/release-gate.yml. It performs three checks:

• Public boundary scan — pnpm check:public-boundary. Hard-fails on PEM private key blocks, merge conflict markers, and RFC1918 private IP literals in non-doc tracked files.
• API contract drift — pnpm check:api-contract. Diffs the source controllers in apps/api/src against scripts/api-routes.snapshot.json and against the table rows in docs/07-api-specification.md. If any side drifts, the gate fails with a precise list of routes that are added, removed, or missing from the docs.
• No internal-only files tracked — fails if any internal-only working file or note slips into the public tree.

Run the gate locally before opening a PR:

pnpm check:release

When you change a controller, also refresh the snapshot so the docs-drift check stays in sync:

pnpm check:api-contract:update

See docs/release-checklist.md for the full maintainer release flow.

Contributions are welcome. See CONTRIBUTING.md for the full guide.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Make your changes, then run pnpm check:release to confirm the release gate still passes.
4. Commit (git commit -m 'feat: add amazing feature').
5. Push to the branch (git push origin feature/amazing-feature).
6. Open a Pull Request.

The Release Checks section above explains what the gate enforces. For controller changes, also see CONTRIBUTING.md → Release Checks.

This project is licensed under the MIT License — see the LICENSE file for details.

• 📖 Documentation · Source
• 🐛 Report a Bug
• 💡 Request a Feature
• 🔒 Security Policy
• 📝 Changelog
• 🕵️ Privacy Policy

Made with ❤️ by the MultiWA team