Your personal WhatsApp backbone. A single self-hosted service that maintains a persistent WhatsApp connection and exposes everything through a clean REST API, real-time WebSocket stream, and webhook system.

Every message, media file, contact, group, call, presence change, and status update is captured and stored in a local SQLite database. Connect all your projects — AI agents, auto-reply bots, dashboards, analytics — to one hub.

WhatsApp  <-->  Baileys Connection  <-->  Event Bus  <-->  SQLite DB
                                            |
                                    REST API + WebSocket
                                            |
                                     Webhook Dispatcher
                                            |
                                   Your projects subscribe

• Full message capture — text, images, video, audio, documents, stickers, locations, contacts, reactions, polls, view-once, forwards, quotes, edits, deletes
• Media auto-download — organized by date in data/media/
• Contacts & groups — names, profile pics, participants, roles, invite codes
• Presence tracking — online/offline/typing/recording status log
• Call log — incoming/outgoing, video/voice, duration
• Status/Stories — captured and stored
• Message receipts — sent/delivered/read/played timestamps per recipient
• Webhook system — HMAC-signed payloads, event filtering, toggle on/off, SSRF protection
• WebSocket streaming — real-time events with optional event type filtering, ticket-based auth
• Full-text search — search across all messages
• Web dashboard — 10-page interactive UI for browsing everything
• Security hardening — database encryption at rest, webhook secret encryption, configurable security toggles
• Docker-ready — single docker compose up to deploy

git clone https://github.com/rafa-rrayes/whatsapp-hub.git
cd whatsapp-hub
cp .env.example .env

Edit .env and set a strong API key:

# Generate a random key
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

docker compose up -d

Open http://localhost:3100 in your browser, enter your API key, and scan the QR code with WhatsApp.

Or check the container logs:

docker compose logs -f

# Check connection status
curl -H "x-api-key: YOUR_KEY" http://localhost:3100/api/connection/status

# Search messages
curl -H "x-api-key: YOUR_KEY" "http://localhost:3100/api/messages/search?q=hello"

# Send a message
curl -X POST -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"jid": "[email protected]", "text": "Hello from WhatsApp Hub!"}' \
  http://localhost:3100/api/actions/send/text

Interactive API docs are available in the dashboard at GET /api.

All requests require an API key via one of:

• Header: x-api-key: YOUR_KEY (recommended)
• Header: Authorization: Bearer YOUR_KEY
• Query param: ?api_key=YOUR_KEY (disabled when SECURITY_DISABLE_HTTP_QUERY_AUTH=true)

import requests

API = "http://localhost:3100/api"
HEADERS = {"x-api-key": "YOUR_KEY"}

# Get unread chats
chats = requests.get(f"{API}/chats", headers=HEADERS).json()
unread = [c for c in chats["data"] if c["unread_count"] > 0]

# Search messages
tasks = requests.get(f"{API}/messages/search", params={"q": "TODO"}, headers=HEADERS).json()

# Reply
requests.post(f"{API}/actions/send/text", headers=HEADERS, json={
    "jid": "[email protected]",
    "text": "Got it! I'll handle that."
})

import WebSocket from "ws";

// With ticket auth (recommended — requires SECURITY_WS_TICKET_AUTH=true)
const res = await fetch("http://localhost:3100/api/ws/ticket", {
  method: "POST",
  headers: { "x-api-key": "YOUR_KEY" },
});
const { ticket } = await res.json();
const ws = new WebSocket(`ws://localhost:3100/ws?ticket=${ticket}&events=wa.messages.upsert`);

// Or with header auth (non-browser)
// const ws = new WebSocket("ws://localhost:3100/ws", { headers: { "x-api-key": "YOUR_KEY" } });

ws.on("message", (data) => {
  const event = JSON.parse(data);
  console.log("New message:", event.type, event.data);
});

Migration notice: Starting with this version, SECURITY_WS_TICKET_AUTH and SECURITY_DISABLE_HTTP_QUERY_AUTH now default to ON (previously OFF). If you rely on query-string API key auth or raw WebSocket connections with ?api_key=, explicitly set SECURITY_WS_TICKET_AUTH=false and/or SECURITY_DISABLE_HTTP_QUERY_AUTH=false in your .env file or Docker Compose environment.

Always-on hardening (no configuration needed): Bearer token parsing fix, WebSocket ping/pong heartbeat, input validation on group operations and order parameters, media URL fetch size limits + timeout, SSRF re-validation at webhook delivery, per-API-key rate limiting.

WhatsApp Hub serves plain HTTP by default. If you place it behind a TLS-terminating reverse proxy (Caddy, nginx, Cloudflare Tunnel, etc.), set:

BEHIND_PROXY=true

This enables:

• HSTS — tells browsers to always use HTTPS for this host
• upgrade-insecure-requests in Content-Security-Policy — tells browsers to load sub-resources over HTTPS
• trust proxy in Express — reads the real client IP from X-Forwarded-For

Leave it at false (the default) when accessing the app directly over HTTP, otherwise all asset loads will fail and you'll see a blank page.

data/
├── whatsapp-hub.db        # SQLite database (WAL mode, optionally encrypted)
├── auth/default/          # Baileys session credentials
└── media/
    └── 2025/01/15/        # Date-organized media files

When SECURITY_ENCRYPT_DATABASE=true, the database is encrypted at rest (AES-256). Existing unencrypted databases are automatically migrated on first start (a backup is created beforehand). No special build steps or system libraries are needed — encryption support is bundled.

npm install
cd frontend && npm install && cd ..
cp .env.example .env
# Set your API_KEY in .env
npm run dev

The frontend dev server runs separately:

cd frontend
npm run dev

Backend: Node.js, TypeScript, Express, Baileys, better-sqlite3 (with encryption), Pino

Frontend: React, TypeScript, Vite, Tailwind CSS, Radix UI, Zustand, TanStack Query, Recharts

MIT