Meet WaSphere

WaSphere is a free, MIT-licensed, self-hosted WhatsApp API platform (GitHub). Instead of paying a BSP per message and waiting on Meta approval, you connect your own WhatsApp number and get a REST API, a web dashboard, multi-session support, and HMAC-signed webhooks.

What "free" actually means here

• No per-message fees — you pay only for your own server.
• No Meta approval process — pair by scanning a QR code.
• MIT license — use it commercially, modify it, fork it.
• Your data never leaves your infrastructure.

Deploy it with Docker

Requirements: Docker Engine 24+ and Docker Compose v2.

git clone https://github.com/wasphere/wasphere.git
cd wasphere
cp .env.example .env
# generate each secret, e.g.: openssl rand -hex 32
docker compose up -d

Open http://localhost:3004, create the first admin account, and connect a WhatsApp number under Sessions with the QR code.

Send messages over a REST API

WaSphere supports 14 message types — text, media, buttons, lists, polls, reactions, location, contacts, and more:

curl -X POST http://localhost:3000/workspaces/{workspaceId}/proxy/api/sessions/{sessionId}/messages/text \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "to": "12125550100", "text": "Your order has shipped!" }'

Incoming messages and delivery receipts arrive at your webhook endpoint, signed with HMAC-SHA256 so you can verify them.

Try before you self-host

There is a seeded live demo at demo.wasphere.com — no signup needed. If you like what you see, the full platform is a docker compose up -d away.

Links: wasphere.com · GitHub · Live demo

Why self-host instead of using the Meta Cloud API?

A self-hosted WhatsApp API runs on your own server and connects to WhatsApp through the same multi-device protocol your phone app uses. You pair it once by scanning a QR code, and from then on your apps talk to a local REST API. That means:

• No Meta approval — no business verification, no template review queues
• No per-message platform fees — your only cost is the VPS
• Full data ownership — conversations never flow through a third-party cloud
• No rate-limit surprises from a shared SaaS tier

Enter WaSphere: an open-source self-hosted WhatsApp API

WaSphere is an open-source (MIT), self-hosted WhatsApp API and developer platform. It gives you:

• Multi-session WhatsApp — connect multiple numbers from one deployment
• A REST API covering 14 message types: text, image, video, audio, document, stickers, location, contact, polls, interactive buttons and lists, reactions, and more
• HMAC-signed webhooks — inbound messages arrive with verifiable X-WaSphere-Signature headers
• Scoped API keys — 12 granular scopes for safe integrations
• A realtime team inbox — a shared dashboard where agents reply to customers live
• One-command Docker deploy — NestJS + Baileys under the hood

It's a practical WhatsApp Business API alternative — a free WhatsApp API you fully control, instead of renting access per conversation.

Deploy it in minutes

Any VPS with Docker will do. This is the actual quick start from the GitHub repo:

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

That starts three services: the dashboard UI on port 3004, the API on 3000, and the WA server on 3001.

1. Open http://localhost:3004 and register your first admin account.
2. Go to Settings → WA Server URL and set http://wa-server:3001 plus your WA_TOKEN.
3. Add a number under Sessions and scan the QR code with WhatsApp (Linked Devices).

Pairing is per number, so you can attach several business numbers to the same instance.

Send your first message

With a session connected, sending is an HTTP call with your API key (Authorization: Bearer wsk_…). The send routes live under the workspace proxy, for example:

POST workspaces/{workspaceId}/proxy/api/sessions/{sessionId}/send

Swap the session ID and recipient, and the message goes out from your own number. The full request reference is built into the product at /docs/wa-server — an interactive Scalar API reference served by your own instance.

Receive messages with signed webhooks

Point WaSphere at your webhook URL and every inbound message and status event is delivered as JSON with a verifiable signature:

X-WaSphere-Signature: v1,sha256=<hmac>
X-WaSphere-Timestamp: <unix-seconds>

The signature is the HMAC-SHA256 of {timestamp}.{rawBody} using your webhook secret. Verify it on receipt and you know the payload genuinely came from your server — this is how you build chatbots, auto-replies, and CRM syncs you can trust.

Put a team on it: the realtime inbox

Unlike raw gateway libraries, WaSphere ships a realtime team inbox in the dashboard. Agents see conversations arrive live, claim threads, and reply — no extra frontend to build. For automation, n8n nodes and WHMCS/Shopify integrations cover the common no-code and billing flows.

Try it before you self-host

There is a live demo at demo.wasphere.com and full docs on the repo. If you've been putting off WhatsApp integration because of the Meta approval process, this is the shortcut: an open-source WhatsApp API on your own infrastructure, deployed before your coffee cools.

Happy self-hosting! 🚀

WaSphere is an open-source (MIT), self-hosted WhatsApp API and developer platform I built for exactly this. It gives you multi-session WhatsApp, a REST API, HMAC-signed webhooks, 14 message types, and a realtime team inbox — all deployed with one docker compose up -d.

In this tutorial I'll take you from zero to sending your first WhatsApp message through your own API in about 10 minutes.

What you get

• Multi-session — run many WhatsApp numbers from one deployment, each with its own API key scope and webhook endpoint. QR-based pairing in seconds.
• REST API — send across 14 message types: text, image, video, audio/voice notes, documents, stickers, GIFs, view-once media, buttons, lists, polls, reactions, locations, and contact cards.
• HMAC-signed webhooks — every delivery is signed (X-WaSphere-Signature: v1,sha256=<hmac> over {timestamp}.{rawBody}), with per-webhook secrets, retries, and SSRF-guarded delivery.
• Realtime team inbox — a two-pane inbox in the dashboard with roles, a contact book CRM, tags/notes, and CSV import/export.
• Security-first — scoped API keys (12 permission scopes), Argon2id-hashed keys, AES-256-GCM encrypted secrets, and a full audit log.
• Anti-ban controls — per-session send delays, typing simulation, and rate limits.

The architecture is two cleanly separated services: a Next.js dashboard with a NestJS API, and a WA Server (NestJS + Baileys) that isolates the WhatsApp engine.

Prerequisites

• Docker Engine 24+ and Docker Compose v2
• A server or your local machine (for a public deployment, bring your own reverse proxy for TLS)

Step 1 — Deploy

git clone https://github.com/wasphere/wasphere.git
cd wasphere
cp .env.example .env
# Set the secrets in .env — generate each with: openssl rand -hex 32
docker compose up -d

Open http://localhost:3004, register the first (admin) account, then go to Settings → WA Server and set the URL to http://wa-server:3001 plus your WA_TOKEN.

Step 2 — Connect a number

In the dashboard, create a session and scan the QR code with WhatsApp. The session goes active instantly — no approval process, no waiting.

Step 3 — Send your first message

Create a scoped API key in the dashboard, then:

curl -X POST https://wa.your-domain.com/api/messages/send \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "my-business",
    "to": "15551234567",
    "text": "Hello from my own WhatsApp API!"
  }'

Response: 200 OK with a messageId. That's it — you're sending WhatsApp messages from your own infrastructure.

Step 4 — Receive webhooks

Register a 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": "my-app", "url": "https://my-app.com/webhook/wa", "events": ["message.received"] }'

Verify the signature in your receiver (Node.js):

const crypto = require("crypto");

function verify(req, secret) {
  const signature = req.headers["x-wasphere-signature"]; // v1,sha256=<hmac>
  const timestamp = req.headers["x-wasphere-timestamp"];
  const expected = "v1,sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${req.rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

This pattern works great for automation — I use it with n8n workflows for order notifications and support routing.

Why self-host instead of the Business API?

• Cost — no per-message fees; you pay for your server.
• Control — your sessions and contacts never leave your infrastructure.
• No approval queues — connect a number and start building.
• Hackable — it's MIT licensed. Fork it, extend it, ship it.

The full source is on GitHub: github.com/wasphere/wasphere. There's a seeded live demo at demo.wasphere.com, and full docs on wasphere.com.

If you self-host your messaging stack, give the repo a star — and let me know what you build with it.