WaSP - WhatsApp Session Protocol

██╗    ██╗ █████╗ ███████╗██████╗
██║    ██║██╔══██╗██╔════╝██╔══██╗
██║ █╗ ██║███████║███████╗██████╔╝
██║███╗██║██╔══██║╚════██║██╔═══╝
╚███╔███╔╝██║  ██║███████║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝

Production-ready infrastructure layer for WhatsApp integrations

Quick Start • Features • Documentation • Examples • Docker

Used in Production

WaSP powers real-world WhatsApp integrations:

• WhatsHub - Multi-tenant WhatsApp messaging platform
• WhatsAuction (whatsauction.co.za) - Live auction bidding via WhatsApp
• FlashVault VPN (flashvault.co.za) - Customer support automation

Why WaSP?

Building WhatsApp integrations is painful. Every project requires re-implementing:

• Session management and persistence
• Multi-tenant isolation
• Anti-ban queueing with human-like delays
• Reconnection logic and error handling
• Provider-specific quirks

WaSP solves this. One unified API across Baileys, Whatsmeow, and Cloud API with batteries included.

Features

• ✅ Unified API - One interface across all WhatsApp providers
• 🏢 Multi-tenant - Isolated sessions per org/user
• 🛡️ Anti-ban queue - Human-like delays, priority lanes
• 💾 Pluggable storage - Memory, Redis, Postgres
• 🔧 Middleware system - Logging, reconnection, rate limiting
• 📘 TypeScript-first - Full type safety
• 🚀 Production-ready - Auto-reconnect, error recovery
• 📡 Event-driven - Normalized events across providers
• 🐳 Docker support - Ready-to-deploy containers

Quick Start

Installation

npm install wasp-protocol @whiskeysockets/baileys

# Optional: For persistence
npm install ioredis  # Redis store
npm install pg       # Postgres store

Basic Usage

import { WaSP } from 'wasp-protocol';

const wasp = new WaSP({
  queue: {
    minDelay: 2000,  // Min 2s between messages
    maxDelay: 5000,  // Max 5s between messages
  },
});

// Create session (QR code authentication)
const session = await wasp.createSession('user-123', 'BAILEYS');

// Listen for QR code
wasp.on('SESSION_QR', (event) => {
  console.log('Scan this:', event.data.qr);
});

// Listen for connection
wasp.on('SESSION_CONNECTED', (event) => {
  console.log('Connected as:', event.data.phone);
});

// Handle incoming messages
wasp.on('MESSAGE_RECEIVED', async (event) => {
  const msg = event.data;
  console.log(`From ${msg.from}: ${msg.content}`);

  // Auto-reply
  if (msg.content === 'hello') {
    await wasp.sendMessage(event.sessionId, msg.from, 'Hi there!');
  }
});

// Send message (auto-queued with anti-ban delay)
await wasp.sendMessage('user-123', '[email protected]', 'Hello!');

Architecture

┌─────────────────────────────────────────┐
│         Your Application                │
│  (SaaS, Bot, Notifications, etc.)       │
└─────────────────────────────────────────┘
                  │
                  │ WaSP Unified API
                  ▼
┌─────────────────────────────────────────┐
│            WaSP Core                    │
│  • Session Manager (multi-tenant)       │
│  • Anti-Ban Queue (priority lanes)      │
│  • Middleware Pipeline                  │
│  • Store (Memory/Redis/Postgres)        │
└─────────────────────────────────────────┘
                  │
       ┌──────────┼──────────┐
       ▼          ▼          ▼
   Baileys  Whatsmeow  Cloud API
       │          │          │
       └──────────┴──────────┘
                  │
           WhatsApp Servers

Core Concepts

Sessions

Multi-tenant session isolation. Each user/org gets their own WhatsApp connection.

// Create session with metadata
await wasp.createSession('org-acme', 'BAILEYS', {
  orgId: 'org-acme',
  metadata: { plan: 'enterprise' },
});

// List sessions by org
const sessions = await wasp.listSessions({ orgId: 'org-acme' });

// Destroy session
await wasp.destroySession('org-acme');

Anti-Ban Queue

Prevents WhatsApp bans with human-like delays and priority lanes.

// Regular message (2-5s delay)
await wasp.sendMessage('session-1', recipient, 'Hello');

// Priority message (1-2.5s delay)
await wasp.sendMessage('session-1', recipient, 'Urgent!', { priority: 10 });

// Immediate (skip queue - use sparingly!)
await wasp.sendMessage('session-1', recipient, 'Alert!', { immediate: true });

Storage

Choose persistence layer based on your needs.

import { WaSP, RedisStore, PostgresStore } from 'wasp-protocol';

// Redis (multi-instance, fast)
const wasp = new WaSP({
  store: new RedisStore({
    host: 'localhost',
    port: 6379,
    keyPrefix: 'wasp:',
  }),
});

// Postgres (queryable, analytics)
const wasp = new WaSP({
  store: new PostgresStore({
    connectionString: 'postgresql://user:pass@localhost/db',
    autoCreate: true,
  }),
});

Middleware

Compose cross-cutting concerns without polluting core logic.

import { logger, autoReconnect, errorHandler } from 'wasp-protocol';

wasp.use(logger());  // Log all events
wasp.use(autoReconnect({ maxAttempts: 5 }));  // Auto-reconnect on disconnect
wasp.use(errorHandler((error) => console.error(error)));

// Custom middleware
wasp.use(async (event, next) => {
  console.log('Before:', event.type);
  await next();
  console.log('After:', event.type);
});

Events

WaSP emits normalized events across all providers:

| Event | Description | |-------|-------------| | SESSION_CONNECTED | Session authenticated | | SESSION_DISCONNECTED | Connection lost | | SESSION_QR | QR code for scanning | | SESSION_ERROR | Error occurred | | MESSAGE_RECEIVED | Incoming message | | MESSAGE_SENT | Outgoing message sent | | MESSAGE_DELIVERED | Message delivered | | MESSAGE_READ | Message read by recipient | | GROUP_JOIN | Bot joined group | | GROUP_LEAVE | Bot left group | | PRESENCE_UPDATE | User online/typing |

wasp.on('MESSAGE_RECEIVED', (event) => {
  console.log(event.data);  // Normalized Message object
});

wasp.on('*', (event) => {
  console.log('Any event:', event.type);
});

Examples

See examples/ directory:

• echo-bot.ts - Simple bot that echoes messages
• webhook-forwarder.ts - Forward messages to webhook
• group-monitor.ts - Monitor and log group activity
• multi-session.ts - Manage 3 sessions simultaneously

Run examples:

npx tsx examples/echo-bot.ts

Docker

Quick Start

# Build and run with Redis
docker-compose up

# Development mode (hot reload)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

Dockerfile

Pre-configured production Dockerfile included. Supports:

• Node.js 20 slim base
• Multi-stage builds
• Auth state persistence
• Environment configuration

See Dockerfile and docker-compose.yml.

CLI Usage

WaSP provides a CLI for testing and development:

# Start interactive session
npx wasp-protocol connect

# Send message
npx wasp-protocol send --to 27821234567 --message "Hello"

# List sessions
npx wasp-protocol list

API Reference

Core Methods

// Session management
createSession(id, provider, options?): Promise<Session>
destroySession(id): Promise<void>
getSession(id): Promise<Session | null>
listSessions(filter?): Promise<Session[]>

// Messaging
sendMessage(sessionId, to, content, options?): Promise<Message>

// Events
on(event, handler): this
off(event, handler): this
once(event, handler): this

// Middleware
use(middleware): this

// Stats
getQueueStats(): QueueStats
getSessionCount(): number

Types

interface Session {
  id: string;
  phone?: string;
  status: SessionStatus;
  provider: ProviderType;
  orgId?: string;
  connectedAt?: Date;
  createdAt: Date;
  lastActivityAt?: Date;
  metadata?: Record<string, unknown>;
}

interface Message {
  id: string;
  from: string;
  to: string;
  type: MessageType;
  content: string;
  timestamp: Date;
  isGroup: boolean;
  groupId?: string;
  mediaUrl?: string;
  mediaMimeType?: string;
}

Full API docs: See TypeScript definitions in src/types.ts.

Comparison

| Feature | WaSP | Raw Baileys | Cloud API | RetentionStack | |---------|------|-------------|-----------|----------------| | Multi-tenant | ✅ Built-in | ❌ DIY | ❌ DIY | ✅ Built-in | | Anti-ban queue | ✅ Built-in | ❌ DIY | ✅ Official | ✅ Paid | | Reconnection | ✅ Auto | ❌ DIY | ✅ Auto | ✅ Auto | | Storage | ✅ Pluggable | ❌ DIY | ☁️ Cloud | ☁️ Hosted | | Middleware | ✅ Built-in | ❌ None | ❌ None | ⚠️ Limited | | TypeScript | ✅ Full | ⚠️ Partial | ✅ Full | ✅ Full | | Cost | 🆓 Free | 🆓 Free | 💰 $0.005-0.09/msg | 💰 $99+/mo | | Self-hosted | ✅ Yes | ✅ Yes | ❌ No | ❌ No | | Provider swap | ✅ Easy | ❌ Rewrite | ❌ Locked | ❌ Locked |

Roadmap

• [x] Baileys provider (v7.0+)
• [x] Memory/Redis/Postgres stores
• [x] Anti-ban queue
• [x] Middleware system
• [x] Docker support
• [x] CLI tool
• [ ] Whatsmeow provider
• [ ] Cloud API provider
• [ ] Webhook system
• [ ] Message templates
• [ ] Admin dashboard UI

Contributing

Contributions welcome! See CONTRIBUTING.md.

git clone https://github.com/kobie3717/wasp.git
cd wasp
npm install
npm test
npm run build

License

MIT © Kobus Wentzel

Support

• Discord: Join our community
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Security

For security issues, email [email protected] instead of using the issue tracker.

Changelog

See CHANGELOG.md for release history.

Built with ❤️ in South Africa

npm • GitHub • Issues