n8n-nodes-multiwa

v2.1.0

Last updated Nov 7, 2026

n8n nodes for MultiWA, the self-hosted WhatsApp API gateway with a built-in team inbox

611 Weekly Downloads

963 Monthly Downloads

View on NPM GitHub Repository

Description

MultiWA

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.

🎯 What is MultiWA?

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.

✨ Why MultiWA?

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

—

🚀 Quick Start

Option 1: Docker — One Command Setup ⚡

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.

Option 2: Local Development

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

—

⚡ Features

Core

📱 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
📞 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

Admin Dashboard

🖥️ 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

Automation & AI

🤖 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

Integrations

🔗 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

Enterprise

🛡️ 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 for durable webhook delivery and

background jobs; with DURABLE_SEND=true outbound sends are enqueued (Redis)
and delivered with retry, and with ENGINE_HOST=worker the 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

—

📸 Screenshots

Contacts
Automation

Profiles
Settings

View all screenshots →

—

🏗️ Architecture

┌──────────────────────────────────────────────────────────┐
│                    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           │
└──────────────────────────────────────────────────────────┘

Tech Stack

—

📖 API Documentation

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

Example: Send a Text Message

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! 👋"
  }'

Example: Connect a WhatsApp Session

curl -X POST http://localhost:3333/api/v1/accounts/YOURACCOUNTID/profiles/YOURPROFILEID/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.

—

📦 SDKs

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).

TypeScript SDK Example

npm install @multiwa/sdk

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! 👋',
});

—

🗂️ Project Structure

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

—

🐳 Production Deployment

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 (JWTSECRET, DBPASSWORD, 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.

—

✅ Release Checks

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.

—

🤝 Contributing

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.

—

📄 License

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

—

🔗 Links

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

—

Made with ❤️ by the MultiWA team