Self-hosted WhatsApp API gateway with a built-in team inbox
Quick Start β’ Features β’ Screenshots β’ Architecture β’ API Docs β’ SDKs β’ Deployment β’ Release Checks β’ Contributing
Warning
MultiWA is not affiliated with WhatsApp or Meta. It connects through WhatsApp Web, and WhatsApp can block or log out numbers that break its terms. Use a number you can afford to lose, and follow WhatsApp's policies.
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.
| Feature | MultiWA | WhatsApp Cloud API | Evolution API |
|---|---|---|---|
| Self-hosted | β Full control | β Meta-hosted | β |
| WhatsApp connection | WhatsApp Web via whatsapp-web.js (a Baileys adapter is experimental) | Meta's official Cloud API | Baileys or the official Cloud API |
| Admin Dashboard | β Full-featured | β None | |
| Visual Automation | β Drag & drop builder | β | β |
| Knowledge Base AI | β OpenAI-compatible | β | β |
| Plugin System | β Extensible | β | β |
| Free | β MIT License | β | |
| Official SDKs | β TS, Python, PHP | β Multiple |
β 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 -dThat'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;
sendReactionandresolveIdentityare 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
- π Call Management β Incoming call history and a follow-up queue (reply, call link, assign, done), reject or auto-reject with an optional reply (at most one per caller per 24 hours), missed-call notifications, and
call.*webhooks; call links need whatsapp-web.js (see Webhook Events) - π§ Calls in the Dashboard (opt-in) β Agents answer WhatsApp voice calls in the browser, on whatsapp-web.js profiles, once the server has HTTPS and one media port open to them. Calls can also be recorded, and the caller then always hears an announcement first; recordings stay private, for owners and admins, and every play, download and delete is audited (see Calls answered in the dashboard)
- π‘ Real-time WebSocket β Live session status, QR codes, and events via Socket.IO
- π Quiet-Profile Alarm β A connected profile that stops receiving messages raises one alarm (admin bell + WhatsApp to your ops numbers through another profile) and a notice when it recovers
- π 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
- π€ Customer Profile β the customer behind a number, beside the chat and in calls: your ID, live data from your system, notes and tags
- π 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) +/metricson the worker health port: default Node/process metrics plus BullMQ queue depth. Public like/healthβ restrict at your proxy/firewall - βοΈ Background Worker β BullMQ worker for durable webhook delivery and
background jobs; with
DURABLE_SEND=trueoutbound sends are enqueued (Redis) and delivered with retry, and withENGINE_HOST=workerthe worker can host the WhatsApp engine itself (default: engine runs in the API process) - π GDPR β Data export and deletion endpoints
- π Plugin System β Extend with custom plugins
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Layer | Technology |
|---|---|
| API | NestJS 10 + Fastify |
| Admin | Next.js 14 + Tailwind CSS |
| Database | PostgreSQL 16 + Prisma ORM |
| Cache/Queue | Redis 7 + BullMQ |
| whatsapp-web.js (production) / Baileys (experimental) | |
| Auth | JWT (access + refresh tokens) |
| Realtime | Socket.IO |
| Container | Docker + Docker Compose |
| CI/CD | GitHub Actions |
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.
The TypeScript SDK is published on npm (npm install @multiwa/sdk), the
Python SDK on PyPI (pip install multiwa), the PHP SDK on Packagist
(composer require multiwa/multiwa-php), and the n8n community node on npm
(npm install n8n-nodes-multiwa).
| Language | Source | Status |
|---|---|---|
| TypeScript/Node.js | packages/sdk |
Published on npm Β· npm install @multiwa/sdk |
| Python | packages/sdk-python |
Published on PyPI Β· pip install multiwa |
| PHP | packages/sdk-php |
Published on Packagist Β· composer require multiwa/multiwa-php |
| n8n community node | packages/n8n-nodes-multiwa |
Published on npm Β· npm install n8n-nodes-multiwa |
npm install @multiwa/sdkimport { 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 (can host the engine)
βββ packages/
β βββ core/ # Shared types and utilities
β βββ database/ # Prisma schema and migrations
β βββ engines/ # WhatsApp engine adapters (whatsapp-web.js, Baileys, mock)
β βββ engine-runtime/ # Shared engine helpers (ack status, media, send gate, β¦)
β βββ sdk/ # TypeScript SDK (`@multiwa/sdk`)
β βββ sdk-python/ # Python SDK (`multiwa`)
β βββ sdk-php/ # PHP SDK (`multiwa/multiwa-php`)
β βββ n8n-nodes-multiwa/ # n8n community node (`n8n-nodes-multiwa`)
β βββ chatwoot-bridge/ # Chatwoot integration
β βββ wordpress-plugin/# WordPress contact-form plugin
βββ plugins/ # Plugin directory (runtime loadable)
βββ docker/ # Dockerfiles + nginx reverse-proxy config
βββ docs/ # Public documentation (mirrored into docs-site)
βββ docs-site/ # Docusaurus documentation site (+ GitHub Pages build)
βββ landing/ # Static landing page assets
βββ 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.ymlwhich 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 inapps/api/srcagainstscripts/api-routes.snapshot.jsonand against the table rows indocs/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:releaseWhen you change a controller, also refresh the snapshot so the docs-drift check stays in sync:
pnpm check:api-contract:updateSee docs/release-checklist.md for the full
maintainer release flow.
Contributions are welcome. See CONTRIBUTING.md for the full guide.
- Fork the repository.
- Create your feature branch (
git checkout -b feature/amazing-feature). - Make your changes, then run
pnpm check:releaseto confirm the release gate still passes. - Commit (
git commit -m 'feat: add amazing feature'). - Push to the branch (
git push origin feature/amazing-feature). - 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




