Package Exports
- wasp-protocol
Readme
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 storeBasic 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', '27821234567@s.whatsapp.net', '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 ServersCore 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.tsDocker
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 upDockerfile
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 simple CLI for testing:
# Start interactive session
npx wasp-protocol connect
# Send message
npx wasp-protocol send --to 27821234567 --message "Hello"
# List sessions
npx wasp-protocol list(CLI coming in v0.3.0)
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(): numberTypes
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
- Baileys provider (v7.0+)
- Memory/Redis/Postgres stores
- Anti-ban queue
- Middleware system
- Docker support
- Whatsmeow provider
- Cloud API provider
- CLI tool
- 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 buildLicense
MIT © Kobus Wentzel
Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: kobie3717@gmail.com
Security
For security issues, email kobie3717@gmail.com instead of using the issue tracker.
Changelog
See CHANGELOG.md for release history.