Zaileys
Zaileys - Simplified WhatsApp Node.js TypeScript/JavaScript API
Install / Use
/learn @zeative/ZaileysREADME
🚀 Overview • 🪶 Features • 📦 Installation • 🏁 Starter Kit • ⚡ Quick Start • 🧩 Plugins • 📨 Sending Messages • 👥 Group Management • 📰 Newsletter Management • 🌐 Community Management • 🔒 Privacy • 🤝 Contributing
<br><a href="https://discord.gg/KBHhTTVUc5"><img alt="Discord" src="https://discord.com/api/guilds/1105833273415962654/widget.png?style=banner2"></a>
</div> </div> <br>🚀 Overview
Zaileys solves the complexity of managing raw WhatsApp socket connections by providing a high-level, opinionated API. It is built for developers who need to create bots, customer support agents, or automated notification systems without getting bogged down in protocol details.
Targeting Node.js and TypeScript developers, Zaileys integrates essential features like rate limiting, session management, and input validation out of the box.
🌟 What's New in v3 (Performance & Stability Core)
- 🚀 Unified Store Architecture: Say goodbye to messy caches! We've elegantly grouped all scattered memory into a single, highly-optimized Registry Pattern. Enjoy zero memory leaks and strict namespaces for absolute peace of mind.
- ⚡ FireAndForget v3 Engine: Background tasks just got superpowers! Now fully event-based with smart priority channels (
CRITICALtoLOW). It automatically prevents queue clogs, handles smart retries, and shuts down gracefully. - 🛡️ Auto-Healing Connections: Maximum uptime, zero headaches! Zaileys now brilliantly catches nasty connection drops (like those sneaky
405stale sessions) and seamlessly auto-reconnects behind the scenes instead of crashing. - 🎬 Decoupled Media Processing: We've trimmed the fat! All FFmpeg and image magic are now safely housed in an ultra-robust standalone package (
@zaadevofc/media-process), making the core platform incredibly lightweight. - 🏎️ Lightning Database & Slim Dependencies: Speed is everything. We crushed bloat by upgrading to blazing-fast
lmdband swapping heavy libraries (zod,lodash) for modern speed demons likevalibotandradashi.
🪶 Features
- ✅ Type-Safe - Full TypeScript +
Valibotvalidation with autocomplete - ✅ Middleware - Intercept and process events globally
- ✅ Plugin System - Drop-in file-based plugins with on/off controls
- ✅ State Management - Built-in LMDB for blazing-fast database persistence with auto chunking for heap safety
- ✅ Rate Limiting - Anti-spam protection powered by lightning-fast native LRU bounds
- ✅ Multi-Device - QR code or Pairing Code authentication
- ✅ Built-in FFmpeg - No external dependencies for media processing
- ✅ Interactive Buttons - Simple buttons, URL, copy code, call buttons, multi-card carousel and lists
- ✅ Auto Clean Up - Periodic database maintenance to save space
🎨 Concepts & Architecture
Client - Your bot's brain. Manages connections, events, and the entire lifecycle.
Context - Rich event objects with all the data and helpers you need.
Middleware - Pre-process events for logging, auth, spam filtering, or custom logic.
Plugins - Drop files in plugins/ directory. Auto-loaded, zero config.
Store - Lightning-fast database (LMDB) that auto-syncs chats, contacts, messages, and cryptographic keys.
📦 Installation
Install zaileys using your preferred package manager:
npm install zaileys
# or
pnpm add zaileys
# or
yarn add zaileys
Note: Requires Node.js v20+ and TypeScript for best experience.
FFmpeg: No need to install FFmpeg separately! It's already bundled with Zaileys for seamless media processing (audio, video, stickers). You can disabled it if you want at
Client Configuration.
🏁 Starter Kit
Prefer a ready-to-run setup? We provide a complete example that covers messages, media, buttons, carousel, polls, and more — ready to copy and go.
👉 examples/basic.ts — Clean, comprehensive starter with all features demonstrated
⚡ Quick Start
Here is a minimal example to get your bot running with QR code authentication:
import { Client } from 'zaileys';
// or
const { Client } = require('zaileys');
const wa = new Client({
// dynamic session you can change
session: 'zaileys', // default
// qr code
authType: 'qr',
// pairing code
authType: 'pairing',
phoneNumber: 6280000000,
// for detailed logs
// fancyLogs: true,
// if you want to disable built-in ffmpeg
// disableFFmpeg: true,
// plugin configuration
pluginsDir: 'plugins', // default
pluginsHmr: true, // default: true (auto reload plugins on change)
sticker: {
authorName: 'your name',
packageName: 'package name',
quality: 80,
shape: 'circle', // output sticker must be circle
},
});
wa.on('messages', async (ctx) => {
if (ctx.text == 'ping') {
await wa.send(ctx.roomId, 'Pong! 🏓');
}
});
{
"uniqueId": "Z4D3FCXXXXXXXXXXXXX",
"channelId": "Z4D3FCXXXXXXXXXXXXX",
"chatId": "ACAE07XXXXXXXXXXXXX",
"chatType": "text",
"receiverId": "628xxxxxxxx@s.whatsapp.net",
"receiverName": "Zaileys",
"roomId": "120xxxxxxxx@g.us",
"roomName": "Group Test",
"senderLid": "272xxxxxxxx@lid",
"senderId": "628xxxxxxxx@s.whatsapp.net",
"senderName": "kejaa",
"senderDevice": "android",
"timestamp": 1766045633000,
"text": "World Hello! https://github.com/zeative/zaileys",
"mentions": ["@628xxxxxxxx", "@123xxxxxxxx"],
"links": ["https://github.com/zeative/zaileys"],
"isBot": false,
"isFromMe": false,
"isPrefix": false,
"isTagMe": false,
"isStatusMention": false,
"isGroupStatusMention": false,
"isHideTags": true,
"isSpam": false,
"isGroup": true,
"isNewsletter": false,
"isQuestion": false,
"isStory": false,
"isViewOnce": false,
"isEdited": false,
"isDeleted": false,
"isPinned": false,
"isUnPinned": false,
"isBroadcast": false,
"isEphemeral": false,
"isForwarded": false,
"citation": {
"authors": [AsyncFunction (anonymous)],
"banned": [AsyncFunction (anonymous)]
},
"media": {
// ...
// buffer promise
// stream promise
},
"message": [Function (anonymous)],
"replied": {} // MessagesContext
}
🛠️ Configuration
The Client constructor accepts a configuration object. Below are the valid options based on the library's type definitions.
General Options
These options apply to both authentication methods:
| Option | Type | Default | Description |
| :---------------- | :-------- | :---------- | :-------------------------------------- |
| session | string | 'zaileys' | Name of the session folder. |
| prefix | string | undefined | Command prefix (e.
Related Skills
imsg
347.9kiMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.
node-connect
347.9kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
oracle
347.9kBest practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
lobster
347.9kLobster Lobster executes multi-step workflows with approval checkpoints. Use it when: - User wants a repeatable automation (triage, monitor, sync) - Actions need human approval before executing (s
