Zaileys

One framework. Two WhatsApp APIs. Zero rewrites.

Zaileys is a type-safe, batteries-included WhatsApp framework for Node.js and TypeScript. Write your bot once against a single chainable builder and fully-typed events — then run it on either provider by flipping one option:

The send(jid).text() builder, the on('text' | 'image' | 'reaction' | …) events, commands, middleware, plugins, storage, broadcast() and scheduleAt() — all identical across both providers. New to Zaileys? Start with Choose Your Provider.

Hello world

The exact same bot logic — only the Client config differs.

import { Client } from 'zaileys'
 
// Default provider — logs in with a QR you scan from your phone.
const client = new Client()
 
client.on('qr', ({ qrString }) => console.log('Scan this QR:', qrString))
client.on('connect', ({ me }) => console.log('Connected as', me.id))
 
client.on('text', async (msg) => {
  await msg.reply(`Hello ${msg.senderName ?? ''}! You said: ${msg.text}`)
})

import { Client } from 'zaileys'
 
// Official provider — a permanent token authenticates you. No QR.
const client = new Client({
  provider: 'cloud',
  cloud: {
    accessToken: process.env.WA_TOKEN!,
    phoneNumberId: process.env.WA_PHONE_ID!,
    verifyToken: process.env.WA_VERIFY!,
    appSecret: process.env.WA_APP_SECRET!,
  },
})
 
client.on('connect', ({ me }) => console.log('Connected as', me.id))
 
client.on('text', async (msg) => {
  await msg.reply(`Hello ${msg.senderName ?? ''}! You said: ${msg.text}`)
})
 
// Inbound arrives via webhook — mount on any server that speaks Web Request/Response.
export const GET = client.webhook()
export const POST = client.webhook()

Prefer a pairing code over scanning a QR on the unofficial provider? Provide your number:

const client = new Client({ authType: 'pairing', phoneNumber: '6281234567890' })
 
client.on('pairing-code', ({ code }) => console.log('Enter this code on your phone:', code))

Which provider should I use?

Full side-by-side breakdown, ToS notes, and a migration guide on Choose Your Provider.

Why Zaileys

• Two providers, one codebase — the unofficial WhatsApp Web engine and the official Meta Cloud API behind the same Client. Switch with a single option; your handlers never change. See Choose Your Provider.
• Typed events — client.on('text' | 'image' | 'reaction' | 'button-click' | 'group-update' | …), each with a fully-typed payload and IntelliSense. No raw Baileys decoding, no any. See Events.
• One chainable builder — client.send(jid).text(…).reply(quoted).mentions([…]) resolves to the sent message key when awaited. See Sending Messages.
• Auto lifecycle — QR or pairing-code login, auto-reconnect with backoff, clean logout, and an optional ignoreMe filter so the bot never replies to itself. See Configuration.
• Rich & interactive out of the box — native buttons, lists, and carousels, plus Meta-AI-style rich responses written as plain markdown. See Interactive Messages and Rich Responses.
• Command framework — register client.command('ping', …) routers with alias support and composable middleware. See Commands.
• Automation — rate-limited broadcast() to many recipients and scheduleAt() for timed sends. See Automation.
• Pluggable storage — independent auth and message stores with file, memory, sqlite, redis, postgres, and convex adapters. See Storage Adapters.
• Media processing — lazy image / video / audio / sticker handling, with an optional sharp accelerator that falls back to a pure-JS path automatically. See Media.
• Runs everywhere — dual ESM/CJS build with .d.ts + .d.cts types; verified on Node, Bun, Deno, and Termux. See Runtimes.
• Modern foundation — Baileys 7.0.0-rc13 (includes the CVE-2026-48063 spoofing patch), built and type-checked with the native TypeScript 7 compiler.

Install

npm i zaileys

pnpm add zaileys

yarn add zaileys

bun add zaileys

Requires Node.js v20+. The file auth store is the zero-config default — nothing else to install to get started. Other storage backends and the sharp media accelerator are optional peer dependencies; install only the ones you use. Full details on the Installation page.

What you can build

Send anything

await client.send(jid).text('Hello there')
await client.send(jid).image('https://example.com/photo.jpg', { caption: 'Nice shot' })
await client.send(jid).poll('Pick one', ['Red', 'Green', 'Blue'])
await client.send(jid).album([
  { type: 'image', src: './a.jpg' },
  { type: 'image', src: './b.jpg' },
])

A JID is a WhatsApp address: 628xxxxxxxxxx@s.whatsapp.net for a person, xxxxxxxxxx@g.us for a group. Inside an event handler you usually just call msg.reply(…) or client.send(msg.senderId).

Interactive messages

Reply, URL, copy, and call buttons — plus lists and carousels — render natively on personal accounts. Taps come back as typed button-click / list-select events.

await client.send(jid).buttons(
  [
    { id: 'yes', text: 'Yes' },
    { type: 'url', text: 'Open docs', url: 'https://github.com/zeative/zaileys' },
    { type: 'copy', text: 'Copy code', code: 'ZAILEYS-2026' },
  ],
  { title: 'Pick one', text: 'Tap a button below' },
)
 
client.on('button-click', (ctx) => console.log('tapped:', ctx.buttonId))

See Interactive Messages for lists, carousels, and every button variant.

Rich responses, written as markdown

Send ordinary markdown — headings, fenced code, tables, and images — and Zaileys renders it as a clean Meta-AI-style response.

await client.send(jid).text(
  ['*Daily brief* ☕', '', '```ts', "console.log('shipped')", '```'].join('\n'),
  { rich: true },
)

See Rich Responses for the full directive set.

A command router with middleware

import { Client, type Middleware } from 'zaileys'
 
const client = new Client({ commandPrefix: ['/', '!'] })
 
const logging: Middleware = async (ctx, next) => {
  console.log(`[command] ${ctx.command} from ${ctx.senderId}`)
  await next()
}
 
client.use(logging)
 
client.command('ping', async (ctx) => ctx.reply('pong'))
client.command('weather', async (ctx) => {
  const city = ctx.args[0]
  await ctx.reply(city ? `Weather in ${city}: sunny, 28°` : 'Usage: /weather <city>')
})

See Commands for aliases, prefixes, and middleware composition.

Broadcast and schedule

await client.broadcast(
  ['6281111111111@s.whatsapp.net', '6282222222222@s.whatsapp.net'],
  (b) => b.text('Maintenance tonight at 22:00.'),
  { rateLimitPerSec: 5, onProgress: (done, total) => console.log(`${done}/${total}`) },
)
 
await client.scheduleAt(new Date('2026-12-31T23:59:00'), (b) =>
  b.text('Happy New Year! 🎉'),
)

See Automation for rate limiting, progress reporting, and persistent schedules.

Build your first bot

The Getting Started guide walks through each step in detail.

Feature matrix

Legend — 🔗 Unofficial (WhatsApp Web) · ☁️ Official (Meta Cloud API) · 🔗☁️ both.

Next steps

• Installation — requirements, package managers, and optional peer dependencies.
• Getting Started — install, authenticate, and run your first bot end-to-end.
• Configuration — every ClientOptions field and its default.
• Events — the full event catalogue and payload shapes.
• Sending Messages — the chainable send builder.
• Interactive Messages and Rich Responses.
• Storage Adapters — persist sessions and history.