Quick start  •  Providers  •  Why Zaileys  •  Install  •  What you can build  •  Storage  •  Runtimes  •  Docs

[!NOTE] This README is a high-level overview. The complete API reference, guides, and recipes live in the documentation site at https://zeative.github.io/zaileys/. Runnable code lives in examples/.

Quick start

There is no await connect() — the client connects on construction, so every handler you register synchronously is wired up before the first event arrives.

import { Client } from 'zaileys'

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(`You said: ${msg.text}`)
})

That is the whole bot. Scan the printed QR via WhatsApp → Linked Devices, and every text message gets a reply.

Prefer a pairing code? Provide your number:

const client = new Client({ authType: 'pairing', phoneNumber: '6281234567890' })

Two providers, one API

Zaileys runs on either the unofficial WhatsApp Web engine or the official Meta WhatsApp Cloud API — same Client, same send(jid)… builder, same typed events. Switch with one option; your handlers never change.

// 🔗 Unofficial (default) — WhatsApp Web via Baileys. QR/pairing login, groups, polls, channels.
const client = new Client()

// ☁️ Official — Meta Cloud API. Token auth, no ban risk, templates/OTP/campaigns, Flows, commerce.
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('text', (m) => m.reply(`echo: ${m.text}`))
await client.sendTemplate('628xxx', 'welcome', 'en_US')  // cloud-only: reach users who never texted you

// inbound arrives via webhook (framework-agnostic) — mount on any server:
export const GET = client.webhook()
export const POST = client.webhook()

| | 🔗 Unofficial (WhatsApp Web) | ☁️ Official (Meta Cloud API) | | --- | --- | --- | | Login | QR / pairing code, no approval | Permanent token | | Ban risk | Exists | None (sanctioned) | | Groups / channels / polls | ✅ | ❌ | | Templates / OTP / marketing | ❌ | ✅ | | Message users who never texted you | ✅ any number | ✅ via approved templates |

Pick your provider → Choose Your Provider · Official Cloud API guide.

Build with AI

Zaileys ships an official Agent Skill suite so your AI assistant writes, reviews, and debugs zaileys code with best practices — it knows the exact API, common pitfalls, and how to fix errors. Install it straight from this repo:

# Claude Code (native plugin — supports auto-update)
/plugin marketplace add zeative/zaileys
/plugin install zaileys-official@zeative

# npx skills (multi-agent: Claude Code, Codex, Cursor, OpenCode)
npx skills add zeative/zaileys        # add -g for a global install

The suite has an orchestrator that auto-routes plus focused scaffold, debug, and review skills. See the full guide → zeative.github.io/zaileys/skill.

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.
• Typed events — on('text' | 'image' | 'reaction' | 'button-click' | 'group-update' | …) with fully-typed payloads and IntelliSense. No raw Baileys decoding, no any.
• One chainable builder — client.send(jid).text(…).reply(quoted).mentions([…]) resolves to the sent message key when awaited.
• Rich & interactive out of the box — native buttons, lists, carousels, and Meta-AI-style rich responses written as plain markdown.
• Auto lifecycle — QR or pairing-code login, auto-reconnect with backoff, clean logout, optional ignoreMe.
• Pluggable storage — independent AuthStore and MessageStore interfaces with file, memory, sqlite, redis, postgres, and convex adapters.
• Batteries included — command framework, broadcast with rate limiting, scheduled sends, and lazy media processing (image/video/audio/sticker).
• Runs everywhere — dual ESM/CJS with .d.ts + .d.cts types; verified on Node, Bun, Deno, and Termux.
• Modern foundation — Baileys 7.0.0-rc13 (includes the CVE-2026-48063 spoofing patch), built and type-checked with the native (Go) TypeScript 7 compiler.

Install

npm i zaileys      # or: pnpm add zaileys  •  yarn add zaileys  •  bun add zaileys

Requires Node.js v20+. The file auth store is the zero-config default and needs nothing else.

Termux / Android: install with npm install zaileys --legacy-peer-deps. A plain npm install tries to compile sharp (a peer dependency of Baileys, no prebuilt ARM binary) and fails; the flag skips it and Zaileys falls back to the bundled jimp path. pnpm/yarn are unaffected.

Other storage backends are optional peer dependencies — install only the one you use:

npm i better-sqlite3   # sqlite adapters
npm i redis            # redis adapters
npm i pg               # postgres adapters
npm i convex           # convex adapters

sharp is an optional accelerator for media/sticker processing; without it Zaileys falls back to a pure-JS path automatically. It is not a Zaileys dependency, but Baileys pulls it in as a peer — on platforms with no prebuilt binary (Termux/Android, some Alpine) install with --legacy-peer-deps to skip it.

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' },
])

Interactive messages

Reply, URL, copy, call, reminder, location, and address buttons — plus lists and carousels — rendered natively on personal accounts.

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))

Rich responses, written as markdown

Toggle { rich: true } and write ordinary markdown — fenced code (syntax-highlighted), tables, images, and ::: directives for products, suggestions, and more.

await client.send(jid).text(
  [
    '*Daily brief* ☕',
    '',
    '```ts',
    "const client = new Client()",
    '```',
    '',
    ':::suggest',
    'See changelog | Upgrade guide',
    ':::',
  ].join('\n'),
  { rich: true, title: '📰 zaileys' },
)

Commands, broadcast & schedule

const client = new Client({ commandPrefix: ['/', '!'] })
client.command('ping', (ctx) => ctx.reply('pong 🏓'))

await client.broadcast(jids, (b) => b.text('Announcement'), { rateLimitPerSec: 5 })
await client.scheduleAt(new Date(Date.now() + 60_000), (b) => b.text('Sends in 1 minute'))

Mutate messages

const key = await client.send(jid).text('Original')
await client.edit(key).text('Edited')
await client.react(key, '👍')
await client.delete(key, { forEveryone: true })
await client.forward(key, otherJid)

Storage

Auth state and message history use two independent interfaces, so you can mix and match — e.g. auth in SQLite, messages in Redis.

import { Client, SqliteAuthStore, RedisMessageStore } from 'zaileys'

const client = new Client({
  auth: new SqliteAuthStore({ database: './auth.db' }),
  store: new RedisMessageStore({ url: 'redis://localhost:6379' }),
})

| Adapter | Auth store | Message store | Peer dependency | | ---------- | ------------------- | ---------------------- | ---------------- | | file | FileAuthStore ⭐ | — | none | | memory | MemoryAuthStore | MemoryMessageStore | none | | sqlite | SqliteAuthStore | SqliteMessageStore | better-sqlite3 | | redis | RedisAuthStore | RedisMessageStore | redis | | postgres | PostgresAuthStore | PostgresMessageStore | pg | | convex | ConvexAuthStore | ConvexMessageStore | convex |

⭐ default. Convex requires deploying the helper functions in examples/convex/ — see that folder's README.

Runtime support

Zaileys ships dual ESM/CJS entry points with type declarations for both module systems, and is verified to load on:

| Runtime | ESM | CJS | | ------- | --- | --- | | Node.js >=20 | ✅ | ✅ | | Bun | ✅ | ✅ | | Deno (--node-modules-dir) | ✅ | ✅ | | Termux (Android) | ✅ | ✅ |

Package managers: npm, pnpm, yarn, and bun are all supported.

Bundling & typecheck troubleshooting

• bun build fails with "Browser build cannot import Node.js builtin" — Zaileys (and baileys underneath) is a Node-only library; bun's bundler defaults to a browser target. Pass the target explicitly: bun build index.ts --target bun (or --target node).
• tsc reports errors inside node_modules (ws, thread-stream, whatsapp-rust-bridge) — upstream declaration issues, not yours. Set "skipLibCheck": true in your tsconfig.json.

Documentation

• 🌐 zeative.github.io/zaileys — full documentation site: guides, API reference, recipes
• 🤖 AI Skill — official Claude Code / npx skills skill
• 📦 examples/ — runnable bots: quickstart, interactive buttons, AIRich, storage adapters, broadcast
• 🔀 MIGRATION.md — upgrading from v3.x to v4.0.0 (breaking changes, side-by-side snippets)
• 🤝 CONTRIBUTING.md — dev setup, tests, commit convention, release flow
• 🔒 SECURITY.md — vulnerability disclosure and supported versions
• 📝 CHANGELOG.md — release history

Issues & feedback

Hit a problem or have a feature request? Open an issue.

• Buy me a coffee ☕ • Ko-Fi • Trakteer
• ⭐ Star the repo on GitHub

License

Distributed under the MIT License. See LICENSE for details.