WaSphere

The self-hosted, open-source WhatsApp API platform.
Multi-session · multi-webhook · developer-first · MIT licensed.

Features • Quick Start • API • Security • Roadmap • Live Demo ↗

✨ Why WaSphere?

WaSphere is a self-hosted WhatsApp API platform for developers, hosting/WHMCS resellers, and billing systems that want a production-grade WhatsApp gateway they fully own — your server, your data, no managed SaaS, no per-message fees, no vendor lock-in.

👉 Try it live (seeded demo, no signup): demo.wasphere.com

🏗️ Architecture

WaSphere is two cleanly separated services so the GPL-licensed WhatsApp engine stays isolated from your application layer:

┌─────────────────┐   HTTPS    ┌──────────────────┐   internal    ┌────────────────────┐
│  Dashboard UI   │ ─────────▶ │   Dashboard API  │ ────────────▶ │     WA Server      │
│  Next.js (3004) │            │ NestJS · Prisma  │   X-Api-Token │ NestJS · Baileys   │
│  sessions/keys/ │ ◀───────── │  Postgres (3000) │ ◀──────────── │   WhatsApp (3001)  │
│  webhooks UI    │            │  auth · proxy    │               │  the GPL boundary  │
└─────────────────┘            └──────────────────┘               └────────────────────┘

• WA Server — the WhatsApp gateway (Baileys), the only component that links the GPL engine.
• Dashboard API — auth (JWT + scoped API keys), workspaces, webhook fan-out, audit log, and a token-injecting proxy to the WA Server.
• Dashboard UI — the management console. Talks only to the Dashboard API; never holds your WA Server token in the browser.

🎯 Features

📥 Inbox — new in v1.1

A realtime, two-pane WhatsApp Inbox right in your dashboard — send, receive, and manage conversations without leaving WaSphere.

📖 Full v1.1 release notes: CHANGELOG → 1.1.0 · try it live: demo.wasphere.com

Core

Messaging — 14 send types

Every type below has a dedicated REST endpoint and is fully implemented in the WA Server.

Delivery & safety: bulk send with per-recipient outcome tracking · configurable per-session send delays + auto-read/receipts (anti-ban) · inbound webhooks for every incoming message and status update.

Security & Auth

Operations

🚀 Quick Start

Requirements: Docker Engine 24+ and Docker Compose v2. (For a public deployment, bring your own reverse proxy for TLS — WaSphere does not bundle one.)

git clone https://github.com/wasphere/wasphere.git
cd wasphere
cp .env.example .env
#   POSTGRES_PASSWORD, JWT_SECRET, ENCRYPTION_KEY, WA_TOKEN,
#   WEBHOOK_SIGNING_SECRET, INTERNAL_WEBHOOK_SECRET
docker compose up -d

Then open http://localhost:3004, register the first (admin) account, and in Settings → WA Server set the URL to http://wa-server:3001 and your WA_TOKEN. Connect a number under Sessions, and you're live.

Full walkthrough: Quick Start docs · Configuration reference

Services

Local development

pnpm install
docker compose -f docker-compose.dev.yml up -d   # Postgres only
pnpm prisma:migrate
pnpm dev                                          # all three packages

📡 API

Requests go through the Dashboard API, which proxies to your WA Server and injects the token. Authenticate with a scoped key: Authorization: Bearer wsk_….

# Send a text message
curl -X POST https://api.your-domain.com/workspaces/{workspaceId}/proxy/api/sessions/{sessionId}/messages/text \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "12125550100", "text": "Hello from WaSphere!" }'

# Register a signed webhook
curl -X POST https://api.your-domain.com/workspaces/{workspaceId}/webhooks \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "name": "n8n", "url": "https://n8n.example.com/webhook/wa", "events": ["message.received"] }'

Every delivery is signed: X-WaSphere-Signature: v1,sha256=<hmac> over {timestamp}.{rawBody}.

Interactive API reference — every endpoint, request/response schema, and try-it-out console ships built-in on both services (at /docs/wa-server and /docs/admin on your own deployment). Explore them live:

• 📘 WA Server API — sessions, messages (all 14 types), contacts, groups
• 📗 Dashboard / Admin API — auth, workspaces, API keys, webhooks, proxy

🔐 Security

• No vendor trust required — sessions and contacts live only on your infrastructure.
• Scoped, hashed API keys — 12 permission scopes plus optional per-session scoping; keys stored Argon2id-hashed, shown once.
• Signed webhooks with SSRF protection — HMAC-SHA256 signatures, per-webhook secrets, exponential-backoff retries, auto-deactivation; outbound delivery is DNS-pinned and blocks private/loopback/link-local/cloud-metadata targets.
• Secrets encrypted at rest — AES-256-GCM for WA Server tokens; secrets only via environment variables, never committed.
• Hardened auth — Argon2id passwords, timing-safe login, JWT refresh-token rotation with reuse detection, registration locks after the first admin.
• Header-only WA token + proxy stripping — the WA Server token is accepted via X-Api-Token only and is stripped from all proxied responses, so it never reaches the browser.

Found a vulnerability? See CONTRIBUTING.md for responsible disclosure.

🛠 Tech Stack

📁 Project Structure

wasphere/
├── packages/
│   ├── wa-server/        # WhatsApp gateway (NestJS + Baileys) — the GPL boundary
│   ├── dashboard-api/    # NestJS + Prisma API: auth, workspaces, webhooks, proxy
│   └── dashboard-ui/     # Next.js dashboard
├── docker-compose.yml        # portable full stack (self-host)
├── docker-compose.dev.yml    # Postgres only (local dev)
├── docker-compose.prod.yml   # Dokploy/Traefik overlay
├── docker-compose.demo.yml   # DEMO_MODE showcase (demo.wasphere.com)
├── CONFIGURATION.md
└── README.md

��️ Roadmap

WaSphere Core is MIT and free forever. Commercial products are built on top of the Core as a dependency — the Core never becomes paid.

🆓 Open-source Core (MIT)

🎯 v1.2 makes WaSphere the only MIT-licensed, self-hostable WhatsApp platform that runs both Baileys (unofficial) and the official Meta Cloud API behind one unified, per-session API. Intelligent routing, cost optimization and the Shopify/WooCommerce integrations are part of WaSphere Pro.

💼 Commercial products (paid · closed-source · built on the Core)

These run on top of WaSphere Core and are developed separately — the Core stays MIT and self-hostable on its own.

• WaSphere for Shopify — WhatsApp order confirmation, abandoned-cart and shipping flows (after v1.2)
• WaSphere for WooCommerce (after Shopify)
• WaSphere for WHMCS — billing & client notifications
• WaSphere Pro (hosted SaaS) — fully managed cloud, no self-hosting

Have a request? Open an issue.

📚 Documentation

🤝 Contributing

1. Fork the repo and create a branch (git checkout -b feature/amazing-feature)
2. Commit your changes (Conventional Commits; include Closes #N)
3. Push and open a Pull Request

See CONTRIBUTING.md for setup, branch naming, and PR guidelines.

📄 License

MIT — free for personal and commercial use. See LICENSE.

The WA Server links Baileys, which depends on libsignal (GPLv3). WaSphere isolates all Baileys code in the WA Server binary; the rest of the platform stays MIT-clean.