Zaileys

https://github.com/zeative/zaileys
Admin
Zaileys is a type-safe TypeScript/JavaScript wrapper around Baileys that simplifies WhatsApp bot...
Tokens:983,140
Snippets:4,879
Trust Score:7.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Complete community setup example (bot.ts)

Source: https://github.com/zeative/zaileys/blob/main/docs/groups/communities.mdx

Sets up a community with two groups on first connect and prints the invite link. Each createGroup() call waits 120 seconds, so the whole setup takes about four minutes.

```ts
import { Client } from 'zaileys'

const client = new Client()
const NAME = 'Bandung Outdoor Club'

client.on('connect', async () => {
  const communities = await client.community.list()
  if (communities.some((community) => community.subject === NAME)) return

  const community = await client.community.create(NAME, 'Hiking and cycling groups in Bandung.')

  await client.community.createGroup('Hiking', ['6281234567890@s.whatsapp.net'], community.id)
  await client.community.createGroup('Cycling', ['6289876543210@s.whatsapp.net'], community.id)

  const groups = await client.community.subGroups(community.id)
  console.log('Groups:', groups.map((group) => group.subject).join(', '))

  const code = await client.community.inviteCode(community.id)
  if (code) console.log(`Invite link: https://chat.whatsapp.com/${code}`)
})
```

--------------------------------

### Install database drivers for custom stores

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/migration.mdx

Command to install the required database drivers for the SQLite and Redis stores used in the configuration example.

```bash
npm install better-sqlite3 redis
```

--------------------------------

### Full command example with middleware and cooldown handling

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/command.md

Shows a complete command setup: creating a client with commandPrefix '/', adding a logging middleware, registering a 'weather' command with cooldown, and handling the 'command-blocked' event for cooldown reasons.

```typescript
import { Client, type Middleware } from 'zaileys'

const client = new Client({ commandPrefix: '/' })

const logger: Middleware = async (ctx, next) => {
  console.log(`[${ctx.command}] ${ctx.senderId}: ${ctx.args.join(' ')}`)
  await next()
}
client.use(logger)

client.command(
  { name: 'weather', description: 'Forecast', usage: '<city>', cooldown: 10 },
  async (ctx) => {
    const city = ctx.args[0] ?? 'London'
    if (ctx.flags['json']) console.log(ctx.json)
    await ctx.reply(`Weather in ${city}: sunny`)
  },
)

client.on('command-blocked', ({ command, reason, retryIn, ctx }) => {
  if (reason === 'cooldown') void ctx.reply(`slow down — retry in ${retryIn}s`)
})
```

--------------------------------

### Postgres adapter setup with connection string

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Uses a Postgres database via pg. Requires npm install pg. The connectionString is taken from the DATABASE_URL environment variable. Tables are created on first use.

```bash
npm install pg
```

```TypeScript
import { Client, PostgresAuthStore, PostgresMessageStore } from 'zaileys'

const url = process.env.DATABASE_URL!

const client = new Client({
  auth: new PostgresAuthStore({ connectionString: url, max: 5 }),
  store: new PostgresMessageStore({ connectionString: url }),
})
```

--------------------------------

### Install optional storage backend adapters

Source: https://github.com/zeative/zaileys/blob/main/README.md

Install optional peer dependencies for storage backends. Only install the one you use; these are not required for the default file store.

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

--------------------------------

### Install Zaileys skill with npx skills

Source: https://github.com/zeative/zaileys/blob/main/docs/ai.mdx

Installs the Zaileys skill into the current project using the skills CLI, so everyone on the project gets it.

```bash
npx skills add zeative/zaileys
```

--------------------------------

### Install Convex client

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Install the Convex client library, required for using ConvexAuthStore and ConvexMessageStore.

```bash
npm install convex
```

--------------------------------

### GET / subscription verification example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/endpoints.md

Example of a successful subscription verification request. The response echoes the hub.challenge value verbatim when hub.mode is 'subscribe' and the verify token matches the configured CloudOptions.verifyToken using a constant-time comparison.

```text
GET /?hub.mode=subscribe&hub.verify_token=my-verify-token&hub.challenge=998873645
→ 200 998873645
```

--------------------------------

### MemoryAuthStore and MemoryMessageStore setup

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Keeps everything in memory and disappears when the process exits. No installation needed. Warning: MemoryAuthStore forgets the login on exit, so a new QR code is required on every start; use for tests only.

```TypeScript
import { Client, MemoryAuthStore, MemoryMessageStore } from 'zaileys'

const client = new Client({
  auth: new MemoryAuthStore(),
  store: new MemoryMessageStore(),
})
```

--------------------------------

### First start output

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/convex-store.mdx

The first start asks for a QR code, like any new login. The output shows the connection process and the connected account.

```text
[zaileys] Connecting to WhatsApp (session: default)...
[zaileys] Scan the QR code above with WhatsApp > Linked devices to authenticate.
[zaileys] Connected as 6281234567890@s.whatsapp.net.
```

--------------------------------

### Initialization and start of game loop

Source: https://github.com/zeative/zaileys/blob/main/docs/templates/source/breakout.html

Sets up resize handler, builds bricks, lays out the game, syncs UI, and starts the animation frame loop.

```javascript
window.addEventListener('resize', layout); buildBricks(); layout(); syncUi(); requestAnimationFrame(frame);
```

--------------------------------

### SQLite adapter setup

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Uses a single database file on disk via better-sqlite3. Requires npm install better-sqlite3@11. Both auth and message stores can share one file; tables are created on first use. The database runs in WAL mode, creating additional -wal and -shm files.

```bash
npm install better-sqlite3@11
```

```TypeScript
import { Client, SqliteAuthStore, SqliteMessageStore } from 'zaileys'

const client = new Client({
  auth: new SqliteAuthStore({ database: './whatsapp.db' }),
  store: new SqliteMessageStore({ database: './whatsapp.db' }),
})
```

--------------------------------

### Cloud provider client example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/client.md

Example of creating a client with cloud provider and using sendTemplate and markRead. Also exports webhook handlers for GET and POST.

```typescript
const client = new Client({
  provider: 'cloud',
  cloud: { accessToken: '...', phoneNumberId: '...', verifyToken: '...', appSecret: '...' },
})
await client.sendTemplate('628xxx', 'welcome', 'en_US')
await client.markRead('wamid.H4s...', { typing: true })

export const GET = client.webhook()
export const POST = client.webhook()
```

--------------------------------

### Install Zaileys and Convex

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/convex-store.mdx

Install the required npm packages.

```bash
npm install zaileys convex
```

--------------------------------

### Checklist for starting a new bot

Source: https://github.com/zeative/zaileys/blob/main/skills/zaileys/workflows/new-bot.md

A checklist of steps to follow when starting a new bot project: look at existing code, settle choices, start from template, build behavior, verify, and hand off.

```text
- [ ] 1. Look at what already exists
- [ ] 2. Settle the choices that change the code
- [ ] 3. Start from the template
- [ ] 4. Build the requested behaviour
- [ ] 5. Verify
- [ ] 6. Hand off
```

--------------------------------

### start: Start playback

Source: https://github.com/zeative/zaileys/blob/main/docs/templates/drum-pad.mdx

Starts the sequencer if unlocked. Resumes audio context if needed, sets up scheduler and animation loop.

```javascript
function start() {
  if (!unlock()) return;
  S.playing = true; S.step = 0; queue = [];
  var go = function () {
    if (!S.playing) return;
    S.nextTime = ac.currentTime + .06;
    scheduler();
    timer = setInterval(scheduler, 25);
    raf = requestAnimationFrame(draw);
  };
  if (ac.state === "running") go(); else ac.resume().then(go);
  renderTransport();
}
```

--------------------------------

### Install sharp with bun

Source: https://github.com/zeative/zaileys/blob/main/docs/installation.mdx

Install the sharp package using bun. This is optional; Zaileys will use it automatically if present.

```bash
bun add sharp
```

--------------------------------

### FileAuthStore setup

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Uses the default auth store, which keeps login data as JSON files. Requires no additional installation. The basePath option specifies the folder for creds.json and signal/.

```TypeScript
import { Client, FileAuthStore } from 'zaileys'

const client = new Client({
  auth: new FileAuthStore({ basePath: './sessions/support-bot' }),
})
```

--------------------------------

### Example greet plugin

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/plugin.md

Example plugin from examples/plugins/greet.ts. Defines a 'greet' command that replies with a greeting using the first argument or 'friend' as default, and includes the plugin directory in the reply.

```typescript
import { definePlugin } from 'zaileys'

export default definePlugin({
  name: 'greet',
  description: 'Greet the chat',
  usage: '<name>',
  async message(ctx: any, plugin: any) {
    const name = ctx.args[0] ?? 'friend'
    await ctx.reply(`Hello, ${name}! (loaded from ${plugin.pluginDir})`)
  },
})
```

--------------------------------

### Install sharp with npm

Source: https://github.com/zeative/zaileys/blob/main/docs/installation.mdx

Install the sharp package using npm. This is optional; Zaileys will use it automatically if present.

```bash
npm install sharp
```

--------------------------------

### SqliteMessageStore usage example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/message-stores.md

Shows how to instantiate a Client with a SqliteMessageStore and a SqliteAuthStore, both using the same database file and table prefix. This example is from the 'Example' section of the SqliteMessageStore documentation.

```typescript
import { Client, SqliteMessageStore } from 'zaileys'

const client = new Client({
  sessionId: 'prod',
  store: new SqliteMessageStore({ database: './.zaileys/store.db', tablePrefix: 'bot1' }),
  auth: new (await import('zaileys')).SqliteAuthStore({ database: './.zaileys/store.db', tablePrefix: 'bot1' }),
})
```

--------------------------------

### Install sharp with yarn

Source: https://github.com/zeative/zaileys/blob/main/docs/installation.mdx

Install the sharp package using yarn. This is optional; Zaileys will use it automatically if present.

```bash
yarn add sharp
```

--------------------------------

### Install Redis package

Source: https://github.com/zeative/zaileys/blob/main/docs/data/storage.mdx

Install the Redis client library version 4, required for using RedisAuthStore and RedisMessageStore.

```bash
npm install redis@4
```

--------------------------------

### Install Node.js and ffmpeg on Termux

Source: https://github.com/zeative/zaileys/blob/main/docs/data/runtimes.mdx

Update packages and install the required runtime and media tools.

```bash
pkg update && pkg upgrade
pkg install nodejs-lts ffmpeg
```

--------------------------------

### Install sharp with pnpm

Source: https://github.com/zeative/zaileys/blob/main/docs/installation.mdx

Install the sharp package using pnpm. This is optional; Zaileys will use it automatically if present.

```bash
pnpm add sharp
```

--------------------------------

### Get elapsed game time

Source: https://github.com/zeative/zaileys/blob/main/docs/templates/source/memory-match.html

Returns the elapsed time in milliseconds since the game started, or 0 if not started.

```javascript
function elapsed() {
  return startedAt ? Date.now() - startedAt : 0;
}
```

--------------------------------

### Client constructor example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/client.md

Shows how to create a Client instance with options for session ID, pairing auth, phone number, and command prefix. Also demonstrates registering event handlers for QR, connect, and text messages.

```typescript
import { Client } from 'zaileys'

const client = new Client({
  sessionId: 'my-bot',
  authType: 'pairing',
  phoneNumber: '6281234567890',
  commandPrefix: ['/', '!'],
})

client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))
client.on('connect', ({ me }) => console.log('Connected as', me.id))

client.on('text', async (msg) => {
  await msg.reply(`You said: ${msg.text}`)
})
```

--------------------------------

### Install Zaileys with bun

Source: https://github.com/zeative/zaileys/blob/main/docs/index.mdx

Installs the Zaileys package using bun. Requires Node.js 20 or newer.

```bash
bun add zaileys
```

--------------------------------

### Create a zaileys Client with full configuration

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/configuration.md

Full configuration example for the zaileys Client. Shows all available options including provider, session, auth, media, plugins, and sticker settings. Use as a reference for setting up a complete client instance.

```typescript
import { Client } from 'zaileys'

const client = new Client({
  provider: 'baileys',
  sessionId: 'main',
  authType: 'pairing',
  phoneNumber: '6281234567890',
  commandPrefix: ['/', '!'],
  cacheSignal: true,
  reconnect: { enabled: true, maxAttempts: 10, initialDelayMs: 1000, maxDelayMs: 60000 },
  authGuard: { maxQrAttempts: 5, maxPairingAttempts: 3 },
  session: { clearAuthOn: ['logged-out'] },
  media: { maxBytes: 32 * 1024 * 1024, allowPrivateNetwork: false, maxConcurrentFfmpeg: 2 },
  operationGuard: { intervalsMs: { 'group.create': 120_000 } },
  presence: { enabled: true, minIntervalMs: 1500 },
  scheduleRateLimitPerSec: 1,
  autoRejectCall: { enabled: true, allow: ['6281234567890'] },
  autoDelete: { maxAgeMs: 7 * 24 * 60 * 60 * 1000, intervalMs: 3600_000 },
  plugins: { dir: './plugins', watch: true, onError: (err, file) => console.error(file, err) },
  sticker: { pack: 'my-pack', author: 'me' },
})
```

--------------------------------

### Check installed zaileys version with bun

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/versioning.mdx

Use this command to see which zaileys version is currently installed in your project. Run it before upgrading to know your starting point.

```bash
bun pm ls | grep zaileys
```

--------------------------------

### Install zaileys v4 with npm

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/migration.mdx

Run this command to install zaileys version 4. Requires Node.js 20 or newer. Database drivers are now optional extras.

```bash
npm install zaileys@4
```

--------------------------------

### Install Zaileys with Hono (Official)

Source: https://github.com/zeative/zaileys/blob/main/docs/quickstart.mdx

Install Zaileys along with Hono and the Node server adapter for the official Cloud API webhook.

```bash
npm install zaileys hono @hono/node-server
```

--------------------------------

### Check installed zaileys version with yarn

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/versioning.mdx

Use this command to see which zaileys version is currently installed in your project. Run it before upgrading to know your starting point.

```bash
yarn why zaileys
```

--------------------------------

### Check installed zaileys version with pnpm

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/versioning.mdx

Use this command to see which zaileys version is currently installed in your project. Run it before upgrading to know your starting point.

```bash
pnpm list zaileys
```

--------------------------------

### Game initialization and rendering setup

Source: https://github.com/zeative/zaileys/blob/main/docs/templates/source/2048.html

Initializes the game variables, UI elements, and sets up initial state. Includes creating the grid, status displays, and event listeners for game controls.

```javascript
var grid = [];
var score = 0;
var best = 0;
var mode = 'play';
var locked = false;
var TEXT = { keep: 'Keep going', win: 'You win!', over: 'Game over' };
var statusEl = document.getElementById('status');
var overlay = document.getElementById('overlay');
var primaryBtn = document.getElementById('primary');
var secondaryBtn = document.getElementById('secondary');
```

```javascript
function newGame() {
  emptyCells();
  addRandomTile();
  addRandomTile();
  render(grid);
  score = 0;
  best = Math.max(best, score);
  mode = 'play';
  locked = false;
  overlay.hidden = true;
  statusEl.textContent = TEXT.keep;
}
function emptyCells() {
  grid = [];
  for (var i = 0; i < 4; i++) {
    grid.push([0, 0, 0, 0]);
  }
}
function addRandomTile() {
  var empty = [];
  for (var r = 0; r < 4; r++) {
    for (var c = 0; c < 4; c++) {
      if (grid[r][c] === 0) empty.push([r, c]);
    }
  }
  if (!empty.length) return;
  var cell = empty[Math.floor(Math.random() * empty.length)];
  grid[cell[0]][cell[1]] = Math.random() < 0.9 ? 2 : 4;
}
```

--------------------------------

### Install Zaileys and Express

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/express.mdx

Install the zaileys and express packages. For editor types, also add @types/express as a dev dependency.

```bash
npm install zaileys express
```

--------------------------------

### Check installed zaileys version with npm

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/versioning.mdx

Use this command to see which zaileys version is currently installed in your project. Run it before upgrading to know your starting point.

```bash
npm list zaileys
```

--------------------------------

### Expected server startup logs

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/express.mdx

The terminal shows a QR code and these lines, in any order, after starting the server.

```text
HTTP API listening on http://127.0.0.1:3000
[zaileys] Connecting to WhatsApp (session: default)...
[zaileys] Scan the QR code above with WhatsApp > Linked devices to authenticate.
```

--------------------------------

### v3 client options example

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/migration.mdx

Shows the v3 Client constructor options. In v4, 'session' becomes 'sessionId', 'prefix' becomes 'commandPrefix', and 'phoneNumber' becomes a string.

```ts
const wa = new Client({
  session: 'zaileys',
  authType: 'pairing',
  phoneNumber: 6281234567890,
  prefix: '/',
  showLogs: true,
})
```

--------------------------------

### Configure Client with plugins dir in bot.ts

Source: https://github.com/zeative/zaileys/blob/main/docs/bots/plugins.mdx

Create this file as bot.ts. It creates a Client with a commandPrefix and points the plugins directory to './plugins'. The dir is relative to the folder you start the bot from and defaults to './plugins'.

```ts
import { Client } from 'zaileys'

const client = new Client({
  commandPrefix: '!',
  plugins: { dir: './plugins' },
})
```

--------------------------------

### scheduleAt() usage example

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/client.mdx

Example of scheduling a text message to be sent on December 24, 2026 at 09:00 +07:00. The builder must start with .to(jid) because the builder has no recipient.

```typescript
const handle = await client.scheduleAt(new Date('2026-12-24T09:00:00+07:00'), (b) =>
  b.to('6281234567890@s.whatsapp.net').text('Merry Christmas from Toko Budi!'),
)
console.log('Scheduled job', handle.id)
```

--------------------------------

### Build a dynamic help menu with client.commands()

Source: https://github.com/zeative/zaileys/blob/main/docs/bots/commands.mdx

Registers three commands (ping, dice, help) with metadata for category, description, and usage, then the help command iterates client.commands() to build a grouped menu that skips hidden commands. The output shows the formatted reply with bold category names.

```ts
client.command({ name: 'ping', description: 'Check the bot is online', category: 'general' }, async (ctx) => {
  await ctx.reply('pong')
})

client.command({ name: 'dice', description: 'Roll a die', usage: '[sides]', category: 'fun' }, async (ctx) => {
  const sides = Number(ctx.args[0] ?? 6)
  await ctx.reply(`You rolled ${Math.ceil(Math.random() * sides)}`)
})

client.command({ name: 'help', aliases: ['menu'], description: 'Show this menu', category: 'general' }, async (ctx) => {
  const sections = new Map<string, string>()
  for (const command of client.commands()) {
    if (command.hidden) continue
    const category = command.category ?? 'other'
    let line = `/${command.name}`
    if (command.usage) line += ` ${command.usage}`
    line += ` — ${command.description ?? ''}`
    const lines = sections.get(category) ?? ''
    sections.set(category, `${lines}${line}\n`)
  }

  let menu = ''
  for (const [category, lines] of sections) {
    menu += `*${category}*\n${lines}\n`
  }
  await ctx.reply(menu.trim())
})
```

```text
*general*
/ping — Check the bot is online
/help — Show this menu

*fun*
/dice [sides] — Roll a die
```

--------------------------------

### error

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/events.mdx

Fires when the automatic connect started by `new Client()` fails, for example due to a missing database package.

```APIDOC
## Event: error

### Description
Fires when the automatic connect started by `new Client()` fails, for example due to a missing database package. It is only emitted while something listens; otherwise the error goes to the logger.

### Event
`error`

### Payload Fields
- **error** (Error) - What went wrong, usually a Zaileys error class (see [Errors](/reference/errors)).

### Example
```ts
client.on('error', ({ sessionId, error }) => {
  console.error(`[${sessionId}] could not connect:`, error.message)
})
```
```

--------------------------------

### Media usage example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/media.md

Demonstrates converting audio to opus, video to mp4 with thumbnail, and creating a sticker with metadata. Shows typical usage of the Media facade.

```typescript
import { Media } from 'zaileys'

// audio -> opus voice note buffer
const opus = await new Media('/tmp/recording.wav').audio.toOpus()

// video -> mp4 h264 + thumbnail
const mp4 = await new Media('https://example.com/clip.gif').video.toMp4()
const thumb = await new Media(buffer).thumbnail.get()

// sticker with metadata
const sticker = await new Media('./pixel.png').sticker.create({ pack: 'my-pack', author: 'me' })
```

--------------------------------

### AutoDeleteSweeper usage example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/automation.md

Shows how to instantiate and start an AutoDeleteSweeper with a SqliteMessageStore. The example sets maxAgeMs to 7 days and intervalMs to 1 hour. The sweeper.start() begins the automatic deletion loop; sweeper.stop() is commented out to show how to stop it.

```typescript
import { AutoDeleteSweeper } from 'zaileys'
import { SqliteMessageStore } from 'zaileys'

const store = new SqliteMessageStore({ database: './store.db' })
const sweeper = new AutoDeleteSweeper({ store, options: { maxAgeMs: 7 * 864e5, intervalMs: 3600_000 } })
sweeper.start()
// sweeper.stop()
```

--------------------------------

### Get Group Metadata Example

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/client.mdx

Fetches group metadata using the group ID and logs the subject and participant count.

```typescript
const info = await client.group.metadata('120363025246125486@g.us')
console.log(`${info.subject}: ${info.participants.length} members`)
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/zeative/zaileys/blob/main/CONTRIBUTING.md

Clones the repository, changes into the project directory, and installs dependencies with pnpm. Requires Node.js >=20 and pnpm 10 (pinned via packageManager).

```bash
git clone https://github.com/zeative/zaileys.git
cd zaileys
pnpm install
```

--------------------------------

### Create a Client and listen for connect event

Source: https://github.com/zeative/zaileys/blob/main/docs/concepts/client.mdx

Initializes a new Client from 'zaileys' and logs the connected user's ID when the 'connect' event fires. This is the basic setup for any bot.

```ts
import { Client } from 'zaileys'

const client = new Client()

client.on('connect', ({ me }) => {
  console.log(`Ready as ${me.id}`)
})
```

--------------------------------

### Get raw Baileys message and reply with image

Source: https://github.com/zeative/zaileys/blob/main/docs/concepts/message-context.mdx

Use msg.message() to get the original Baileys message object, required for quoting with the send builder. In this example, when the text 'chart' is received, the bot sends an image and replies with the raw message.

```TypeScript
client.on('text', async (msg) => {
  if (msg.text === 'chart') {
    await client.send(msg.roomId ?? msg.senderId).image('./chart.png').reply(msg.message())
  }
})
```

--------------------------------

### v4 client options example

Source: https://github.com/zeative/zaileys/blob/main/docs/releases/migration.mdx

Shows the v4 Client constructor options. The default session name is now 'default', 'phoneNumber' is a string, and 'commandPrefix' keeps commands off until set.

```ts
import { Client } from 'zaileys'

const client = new Client({
  sessionId: 'zaileys',
  authType: 'pairing',
  phoneNumber: '6281234567890',
  commandPrefix: '/',
})
```

--------------------------------

### Start the daily schedule only once

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/scheduled-broadcast.mdx

Registers a connect handler that guards with a started flag so reconnect events do not create additional daily timers. Without the flag, each reconnect would add another timer and subscribers would get duplicate messages.

```ts
declare function scheduleNextRun(): void

let started = false
client.on('connect', () => {
  if (started) return
  started = true
  scheduleNextRun()
})
```

--------------------------------

### Export webhook handler in Next.js route

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/client.mdx

Example of using webhook() in a Next.js route file (app/api/whatsapp/route.ts). The returned handler is exported as both GET and POST.

```ts
const webhook = client.webhook()

export const GET = webhook
export const POST = webhook
```

--------------------------------

### initializeFFmpeg

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/media.md

Resolves the ffmpeg/ffprobe binaries, either from bundled ffmpeg-static or system installation. Must be called before first use.

```APIDOC
## initializeFFmpeg

### Description
Resolves the ffmpeg/ffprobe binaries (bundled or system). Call before first use.

### Method
initializeFFmpeg

### Parameters
- **disable** (boolean) - Optional - If true, disables initialization.

### Returns
Promise<void>
```

--------------------------------

### Listen to 'command-not-found' event

Source: https://github.com/zeative/zaileys/blob/main/docs/bots/commands.mdx

Reply to unknown commands. Fires when a message starts with the prefix but matches no command. The example skips group messages to avoid noise.

```TypeScript
client.on('command-not-found', async ({ command, message }) => {
  if (message.isGroup) return
  await message.reply(`There's no /${command} command. Send /help to see what I can do.`)
})
```

--------------------------------

### CloudModule usage example

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/cloud.md

Shows how to use the CloudModule to create a template, get it, send a flow, create a QR code, and request/verify a phone code. Requires provider 'cloud'.

```typescript
const cloud = client.cloud // provider must be 'cloud'

await cloud.templates.create({
  name: 'welcome',
  category: 'UTILITY',
  language: 'en_US',
  components: [{ type: 'BODY', text: 'Hello {{1}}' }],
})
const tpl = await cloud.templates.get('welcome')
await cloud.flows.send('628xxx', { cta: 'Open', bodyText: 'Pick a city', screen: 'CITY', flowName: 'order-flow' })
await cloud.qr.create('Scan me', 'PNG')
await cloud.phone.requestCode('SMS', 'en_US')
await cloud.phone.verifyCode(code)
```

--------------------------------

### Start the bot with CONVEX_URL and npx tsx bot.ts

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/convex-store.mdx

Set the CONVEX_URL environment variable to your deployment URL (ending in `.convex.cloud`) and start the bot. Then scan the QR code from WhatsApp → Settings → Linked devices → Link a device.

```bash
export CONVEX_URL="https://happy-otter-123.convex.cloud"
npx tsx bot.ts
```

--------------------------------

### Unofficial startup output

Source: https://github.com/zeative/zaileys/blob/main/docs/quickstart.mdx

Expected terminal output when starting the bot: shows connecting and QR code instructions.

```text
[zaileys] Connecting to WhatsApp (session: default)...
[zaileys] Scan the QR code above with WhatsApp > Linked devices to authenticate.
```

--------------------------------

### Define a plugin with definePlugin

Source: https://github.com/zeative/zaileys/blob/main/skills/zaileys/references/bots.md

Example of a plugin that defines a 'dice' command with aliases, a cooldown, a message handler, a groupJoin event, and a setup function that registers an extra command and returns a teardown.

```TypeScript
import { definePlugin } from 'zaileys'

export default definePlugin({
  name: 'dice',
  aliases: ['roll'],
  description: 'Roll a die',
  cooldown: 3,
  message: async (ctx) => {
    const sides = Number(ctx.args[0] ?? 6)
    await ctx.reply(`You rolled ${Math.ceil(Math.random() * sides)}`)
  },
  groupJoin: async (event, plugin) => {
    try {
      await plugin.client.send(event.groupId).text('Welcome!')
    } catch (error) {
      plugin.logger?.error(error, 'welcome failed')
    }
  },
  setup(plugin) {
    plugin.command({ name: 'dice stats', description: 'Roll history' }, async (cmd) => {
      await cmd.reply('No rolls yet.')
    })
    const timer = setInterval(() => undefined, 60_000)
    return () => clearInterval(timer)
  },
})

```

--------------------------------

### bot.ts - Client setup with plugins

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/plugin-starter.mdx

Creates a `Client` with a command prefix `!` and a plugins directory. Enables hot reload when not in production, and logs errors when a plugin fails to load. Also listens for the `command-not-found` event to reply to unknown commands.

```ts
import { Client } from 'zaileys'

const client = new Client({
  commandPrefix: '!',
  plugins: {
    dir: './plugins',
    watch: process.env.NODE_ENV !== 'production',
    onError: (error, file) => console.error(`Could not load ${file}:`, error),
  },
})

client.on('command-not-found', ({ command, message }) => {
  message.reply(`There's no !${command} command. Try !hello.`).catch(console.error)
})
```

--------------------------------

### Send hello_world template with client.sendTemplate

Source: https://github.com/zeative/zaileys/blob/main/docs/cloud/setup.mdx

Sends the 'hello_world' template to a phone number added as a recipient in Meta's API Setup. A new conversation must start with a template; this is the default template for new apps.

```ts
await client.sendTemplate('6281234567890', 'hello_world', 'en_US')
```

--------------------------------

### v3 plugin definition and Client with pluginsDir and citation

Source: https://github.com/zeative/zaileys/blob/main/skills/zaileys/references/migration.md

Legacy v3 API example for plugins and citation. Shows definePlugins with a matcher, wa.inject for configuration, and Client with pluginsDir and citation.premium. Marked as v3 API and skipped by snippet checks.

```ts
export default definePlugins(async (wa, ctx) => {
  await wa.send(ctx.messages.roomId, 'Hello from plugin!')
}, { matcher: ['/hello'] })

wa.inject('config', { storeName: 'Toko Budi' })
const wa = new Client({ pluginsDir: 'plugins', citation: { premium: async () => [6281234567890] } })
```

--------------------------------

### Send an event invitation

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/send-builder.mdx

Example of sending an event invitation with a name, start and end times, and a location. Requires a valid group JID and a non-empty name; startAt and endAt must be valid Date or epoch ms.

```ts
await client.send('120363025246125486@g.us').event({
  name: 'Monthly team dinner',
  startAt: new Date('2026-10-02T19:00:00+07:00'),
  endAt: new Date('2026-10-02T21:00:00+07:00'),
  location: { latitude: -6.2297, longitude: 106.8295, name: 'Plaza Senayan' },
})
```

--------------------------------

### Run the bot (unofficial provider)

Source: https://github.com/zeative/zaileys/blob/main/docs/recipes/auto-reply.mdx

Starts the bot with the unofficial provider. The terminal shows a QR code and connection messages. Scan the QR code with WhatsApp > Linked devices to authenticate.

```bash
npx tsx bot.ts
```

```text
[zaileys] Connecting to WhatsApp (session: default)...
[zaileys] Scan the QR code above with WhatsApp > Linked devices to authenticate.
```

```text
[zaileys] Connected as 6281234567890@s.whatsapp.net.
```

--------------------------------

### Drum pad JavaScript logic

Source: https://github.com/zeative/zaileys/blob/main/docs/templates/source/drum-pad.html

Core JavaScript for the drum pad: text labels, pad definitions, step sequencer constants, example pattern, icons, audio context setup, sound synthesis functions, and sound definitions.

```javascript
var TEXT = { play: "Play beat", stop: "Stop", bpm: "BPM", hint: "Tap squares to edit", cleared: "Beat cleared", example: "Example loaded", noSound: "No sound here" }; var PADS = [ { name: "Kick", emoji: "💥", a: "#ff4f8b", b: "#ff8a3d", d: "#a8284f" }, { name: "Snare", emoji: "🥁", a: "#ff8a3d", b: "#ffc93c", d: "#b85a1e" }, { name: "Clap", emoji: "👏", a: "#ffc93c", b: "#9be15d", d: "#a57f12" }, { name: "Hi-hat", emoji: "🎩", a: "#9be15d", b: "#2ed8a7", d: "#4f8f2a" }, { name: "Open hat", emoji: "🔔", a: "#2ed8a7", b: "#38b6ff", d: "#17866a" }, { name: "Tom", emoji: "🛢️", a: "#38b6ff", b: "#7c5cff", d: "#1f6fae" }, { name: "Cowbell", emoji: "🐮", a: "#7c5cff", b: "#b44cff", d: "#4b2fb0" }, { name: "Rim", emoji: "🥢", a: "#b44cff", b: "#ff4f8b", d: "#7422b0" }, { name: "Sparkle", emoji: "✨", a: "#ffc93c", b: "#ff4f8b", d: "#b0355e" } ]; var STEPS = 8, MIN_BPM = 60, MAX_BPM = 180; var EXAMPLE = [[0, 4, 5], [2, 6], [], [0, 1, 2, 3, 4, 5, 6], [7], [], [], [], []]; var ICON = { vol: '<svg viewBox="0 0 24 24"><path d="M11 5 6 9H2v6h4l5 4z" fill="currentColor"/><path d="M15.5 8.5a5 5 0 0 1 0 7M19 5a10 10 0 0 1 0 14"/></svg>', mute: '<svg viewBox="0 0 24 24"><path d="M11 5 6 9H2v6h4l5 4z" fill="currentColor"/><path d="m22 9-6 6M16 9l6 6"/></svg>', play: '<svg viewBox="0 0 24 24"><path d="M7 4.5v15L19.5 12z" fill="currentColor"/></svg>', stop: '<svg viewBox="0 0 24 24"><rect x="6" y="6" width="12" height="12" rx="2" fill="currentColor"/></svg>' }; var AC = window.AudioContext || window.webkitAudioContext; var ac = null, master = null, comp = null, timer = 0, raf = 0, openHat = null; var S = { bpm: 110, muted: false, playing: false, step: 0, nextTime: 0, screen: "pads", now: -1 }; var pattern = [], queue = [], padEls = [], cellEls = []; var stats = { voices: 0 }; var $ = function (id) { return document.getElementById(id); }; function buildChain(c) { var m = c.createGain(), k = c.createDynamicsCompressor(); k.threshold.value = -10; k.knee.value = 8; k.ratio.value = 4; k.attack.value = .002; k.release.value = .15; m.connect(k); k.connect(c.destination); return { master: m, comp: k }; } function noiseBuf(c) { if (c.zNoise) return c.zNoise; var b = c.createBuffer(1, c.sampleRate, c.sampleRate), d = b.getChannelData(0); for (var i = 0; i < d.length; i++) d[i] = Math.random() * 2 - 1; return (c.zNoise = b); } function osc(c, out, type, f, t, vol, decay, o) { o = o || {}; var n = c.createOscillator(), g = c.createGain(); n.type = type; n.frequency.setValueAtTime(f, t); if (o.to) n.frequency.exponentialRampToValueAtTime(o.to, t + (o.toT || .1)); g.gain.setValueAtTime(0, t); g.gain.linearRampToValueAtTime(vol, t + (o.a || .002)); g.gain.exponentialRampToValueAtTime(.0005, t + decay); n.connect(g); g.connect(out); n.start(t); n.stop(t + decay + .03); stats.voices++; return g; } function noise(c, out, t, vol, decay, type, f, q) { var s = c.createBufferSource(), fl = c.createBiquadFilter(), g = c.createGain(); s.buffer = noiseBuf(c); fl.type = type; fl.frequency.value = f; fl.Q.value = q || .7; g.gain.setValueAtTime(0, t); g.gain.linearRampToValueAtTime(vol, t + .002); g.gain.exponentialRampToValueAtTime(.0005, t + decay); s.connect(fl); fl.connect(g); g.connect(out); s.start(t, Math.random() * .5); s.stop(t + decay + .03); stats.voices++; return g; } function choke(t) { if (openHat) { openHat.gain.cancelScheduledValues(t); openHat.gain.setTargetAtTime(0, t, .012); openHat = null; } } var SOUNDS = [ function (c, out, t) { osc(c, out, "sine", 155, t, .95, .42, { to: 45, toT: .14 }); osc(c, out, "triangle", 420, t, .25, .04, { to: 90, toT: .03 }); }, function (c, out, t) { noise(c, out, t, .75, .2, "bandpass", 1900, .6); osc(c, out, "triangle", 190, t, .4, .12, { to: 120, toT: .08 }); }, function (c, out, t) { for (var i = 0; i < 3; i++) noise(c, out, t + i * .011, .9, .03, "bandpass", 1150, 1.4); noise(c, out, t + .033, .9, .22, "bandpass", 1150, 1.1); }, function (c, out, t) { choke(t); noise(c, out, t, .6, .06, "highpass", 7000, .9); }, function (c,
```

--------------------------------

### Listen for background errors with client.on('error')

Source: https://github.com/zeative/zaileys/blob/main/docs/data/error-handling.mdx

Listen for background connection errors when using the default autoConnect. The client emits 'error' if the connection fails, for example when a database package is missing. Check for ZaileysStoreError with code 'STORE_NOT_AVAILABLE' to prompt installing the database package.

```ts
import { Client, SqliteAuthStore, ZaileysStoreError } from 'zaileys'

const client = new Client({ auth: new SqliteAuthStore({ database: './whatsapp.db' }) })

client.on('error', ({ sessionId, error }) => {
  if (error instanceof ZaileysStoreError && error.code === 'STORE_NOT_AVAILABLE') {
    console.error(`[${sessionId}] Install the database package: ${error.message}`)
    return
  }
  console.error(`[${sessionId}] Could not connect:`, error)
})
```

--------------------------------

### Hono: Install dependencies and mount webhook on Hono server

Source: https://github.com/zeative/zaileys/blob/main/docs/cloud/webhook.mdx

Install zaileys, hono, and @hono/node-server, then set up a Hono server. The webhook URL is https://<your-domain>/webhook. c.req.raw is the original Web Request, so it passes straight through.

```bash
npm install zaileys hono @hono/node-server
```

```ts
import { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { Client } from 'zaileys'

const client = new Client({
  provider: 'cloud',
  cloud: {
    accessToken: process.env.WA_TOKEN!,
    phoneNumberId: process.env.WA_PHONE_ID!,
    verifyToken: process.env.WA_VERIFY_TOKEN!,
    appSecret: process.env.WA_APP_SECRET!,
  },
})

client.on('text', async (msg) => {
  await msg.reply(`You said: ${msg.text}`)
})

const webhook = client.webhook()
const app = new Hono()
app.all('/webhook', (c) => webhook(c.req.raw))

serve({ fetch: app.fetch, port: 3000 })
```

--------------------------------

### Express: Install dependencies and mount webhook with raw body

Source: https://github.com/zeative/zaileys/blob/main/docs/cloud/webhook.mdx

Install zaileys and express, then set up an Express server. The route builds a Web Request from the raw body and copies the Response back. Register before any app.use(express.json()) so the signature is checked against the raw bytes. Your webhook URL is https://<your-domain>/webhook.

```bash
npm install zaileys express
```

```ts
import express from 'express'
import { Client } from 'zaileys'

const client = new Client({
  provider: 'cloud',
  cloud: {
    accessToken: process.env.WA_TOKEN!,
    phoneNumberId: process.env.WA_PHONE_ID!,
    verifyToken: process.env.WA_VERIFY_TOKEN!,
    appSecret: process.env.WA_APP_SECRET!,
  },
})

client.on('text', async (msg) => {
  await msg.reply(`You said: ${msg.text}`)
})

const webhook = client.webhook()
const app = express()

// Register before any app.use(express.json()) so the signature is checked against the raw bytes.
app.all('/webhook', express.raw({ type: '*/*' }), async (req, res) => {
  const request = new Request(`${req.protocol}://${req.get('host')}${req.originalUrl}`, {
    method: req.method,
    headers: req.headers as Record<string, string>,
    ...(req.method === 'POST' ? { body: req.body as Buffer } : {}),
  })
  const response = await webhook(request)
  res.status(response.status).send(await response.text())
})

app.listen(3000)
```

--------------------------------

### Manual plugin loading with PluginRegistry and PluginLoader

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/plugin.md

Shows manual plugin loading: create a PluginRegistry and PluginLoader with options, start the loader, list loaded plugins, and stop. The example imports definePlugin from the 'zaileys' root; the loader and registry classes come from the plugin module re-export. The watch option enables hot reload with debounced file changes.

```typescript
import { PluginRegistry, PluginLoader, definePlugin } from 'zaileys'

const registry = new PluginRegistry({ client, logger })
const loader = new PluginLoader({
  registry,
  options: { dir: './plugins', watch: true, onError: (err, file) => console.error(file, err) },
})
await loader.start()
console.log(registry.list()) // ['greet', ...]
await loader.stop()
```

--------------------------------

### client.commands() - List commands and build a menu

Source: https://github.com/zeative/zaileys/blob/main/docs/reference/commands.mdx

Returns every registered command in registration order as a RegisteredCommand. The example builds a menu string from non-hidden commands and replies with it.

```ts
let menu = ''
for (const command of client.commands()) {
  if (command.hidden) continue
  menu += `/${command.name} — ${command.description ?? ''}\n`
}

await ctx.reply(menu)
```

--------------------------------

### Registering commands and middleware

Source: https://github.com/zeative/zaileys/blob/main/_autodocs/api-reference/client.md

Demonstrates registering commands and middleware with a commandPrefix. The example shows a ping command, an echo command with a spec object, and how to list registered commands.

```typescript
const client = new Client({ commandPrefix: '/' })
client.use(async (ctx, next) => { console.log(ctx.command); await next() })
client.command('ping', async (ctx) => { await ctx.reply('pong') })
client.command({ name: 'echo', description: 'repeat', usage: '<text>' }, async (ctx) => {
  await ctx.reply(ctx.args.join(' '))
})
console.log(client.commands()) // [{ name: 'echo', aliases: [], description: ..., usage: ... }]
```
Tokens:
Raw