Zaileys

https://zeative.github.io/zaileys
Admin
A type-safe, batteries-included WhatsApp framework built on Baileys for creating bots with typed...
Tokens:67,720
Snippets:679
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Convex Peer Dependency (bun)

Source: https://zeative.github.io/zaileys/storage

Install the Convex peer dependency using bun.

```bash
bun add convex
```

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

### Install Optional Peer Dependencies using npm

Source: https://zeative.github.io/zaileys/installation

Install optional peer dependencies for specific storage adapters using npm. Install only the drivers you intend to use.

```bash
npm i better-sqlite3   # SQLite adapters
npm i pg               # PostgreSQL adapters
npm i redis            # Redis adapters
npm i convex           # Convex adapters
```

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

### Install Zaileys using bun

Source: https://zeative.github.io/zaileys/installation

Use this command to install the Zaileys package with bun.

```bash
bun add zaileys
```

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

### Install Optional Peer Dependencies using pnpm

Source: https://zeative.github.io/zaileys/installation

Install optional peer dependencies for specific storage adapters using pnpm. Install only the drivers you intend to use.

```bash
pnpm add better-sqlite3   # SQLite adapters
pnpm add pg               # PostgreSQL adapters
pnpm add redis            # Redis adapters
pnpm add convex           # Convex adapters
```

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

### Install Convex Peer Dependency (pnpm)

Source: https://zeative.github.io/zaileys/storage

Install the Convex peer dependency using pnpm.

```bash
pnpm add convex
```

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

### Install Convex Peer Dependency (npm)

Source: https://zeative.github.io/zaileys/storage

Install the Convex peer dependency using npm.

```bash
npm i convex
```

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

### Client Lifecycle Example

Source: https://zeative.github.io/zaileys/client

A complete example demonstrating the client's lifecycle, including connection, event handling for QR scanning, reconnections, errors, and connection events. It also shows how to send a text message and react to it, and how to gracefully disconnect.

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

const client = new Client({ sessionId: 'demo', autoConnect: false })

client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))
client.on('reconnecting', ({ attempt, delayMs }) =>
  console.log(`reconnecting #${attempt} in ${delayMs}ms`)
)
client.on('error', ({ error }) => console.error('client error:', error.message))

client.on('connect', async ({ me }) => {
  console.log('connected as', me.id)
  await client.presence.online()
})

client.on('text', async (ctx) => {
  if (ctx.text?.toLowerCase() === 'ping') {
    const key = await client.send(ctx.roomId).text('pong')
    await client.react(key, '🏓')
  }
})

await client.connect()

// later, on shutdown:
process.on('SIGINT', async () => {
  await client.disconnect()
  process.exit(0)
})
```

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

### Install Sharp Image Accelerator with Bun

Source: https://zeative.github.io/zaileys/installation

Install the 'sharp' package, an optional native accelerator for image processing, using Bun.

```bash
bun add sharp
```

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

### Full Zaileys Client Configuration Example

Source: https://zeative.github.io/zaileys/configuration

An example demonstrating the full surface of `ClientOptions`, including session ID, authentication, phone number, command prefix, citation settings, reconnection, auto-connect, QR terminal, status logging, signal caching, logger, and Baileys configuration.

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

const client = new Client({
  sessionId: 'production-bot',
  authType: 'pairing',
  phoneNumber: '628xxxxxxxxxx',
  auth: new SqliteAuthStore({ database: './zaileys.db' }),
  store: new SqliteMessageStore({ database: './zaileys.db' }),
  commandPrefix: ['/', '!'],
  ignoreMe: true,
  citation: {
    authors: ['628xxx@s.whatsapp.net'],
    banned: (jid) => jid.startsWith('62800'),
  },
  reconnect: {
    maxAttempts: 20,
    initialDelayMs: 2000,
    maxDelayMs: 30000,
    jitterFactor: 0.25,
  },
  autoConnect: true,
  qrTerminal: false,
  statusLog: true,
  cacheSignal: true,
  logger: {
    info: (...a) => console.log('[info]', ...a),
    warn: (...a) => console.warn('[warn]', ...a),
    error: (...a) => console.error('[error]', ...a),
  },
  baileys: {
    browser: ['zaileys', 'Chrome', '1.0.0'],
  },
})

client.on('pairing-code', ({ code }) => console.log('Pairing code:', code))
client.on('connect', ({ me }) => console.log('Connected as', me.id))

client.command('ping', async (ctx) => {
  await ctx.reply('pong')
})
```

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

### Install Optional Peer Dependencies using yarn

Source: https://zeative.github.io/zaileys/installation

Install optional peer dependencies for specific storage adapters using yarn. Install only the drivers you intend to use.

```bash
yarn add better-sqlite3   # SQLite adapters
yarn add pg               # PostgreSQL adapters
yarn add redis            # Redis adapters
yarn add convex           # Convex adapters
```

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

### Install Zaileys using npm

Source: https://zeative.github.io/zaileys/installation

Use this command to install the Zaileys package with npm.

```bash
npm i zaileys
```

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

### Install storage adapter drivers with npm

Source: https://zeative.github.io/zaileys/runtimes

Installs specific database drivers for Zaileys storage adapters using npm. Choose the driver corresponding to your chosen backend.

```bash
npm i better-sqlite3   # SQLite
npm i pg               # Postgres
npm i redis            # Redis
```

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

### Initializing Zaileys Client in Bun

Source: https://zeative.github.io/zaileys/runtimes

Example of initializing the Client with QR code authentication in a Bun project.

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

const client = new Client({ authType: 'qr' })
await client.connect()
```

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

### Install Redis Adapter

Source: https://zeative.github.io/zaileys/storage

Use this command to add the Redis adapter to your project.

```bash
bun add redis
```

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

### Install redis for Redis Storage

Source: https://zeative.github.io/zaileys/storage

Install the 'redis' package to enable Redis storage for authentication and message history.

```bash
npm i redis
```

```bash
pnpm add redis
```

```bash
yarn add redis
```

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

### Install storage adapter drivers with pnpm

Source: https://zeative.github.io/zaileys/runtimes

Installs specific database drivers for Zaileys storage adapters using pnpm. `better-sqlite3` is configured to build native components during installation.

```bash
pnpm add better-sqlite3
pnpm add pg
pnpm add redis
```

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

### Install Sharp Image Accelerator with npm

Source: https://zeative.github.io/zaileys/installation

Install the 'sharp' package, an optional native accelerator for image processing, using npm.

```bash
npm i sharp
```

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

### Install Convex Peer Dependency (yarn)

Source: https://zeative.github.io/zaileys/storage

Install the Convex peer dependency using yarn.

```bash
yarn add convex
```

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

### QR Login with Custom Expiry Logging

Source: https://zeative.github.io/zaileys/getting-started

Configure the client for QR login and log the QR string and its expiry time. This example shows how to handle the 'qr' event to get the raw QR string.

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

const client = new Client() // authType defaults to 'qr'

client.on('qr', ({ qrString, expiresAt }) => {
  console.log('Scan this QR string:', qrString)
  console.log('Expires at:', new Date(expiresAt).toISOString())
})
```

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

### Install Zaileys using yarn

Source: https://zeative.github.io/zaileys/installation

Use this command to install the Zaileys package with yarn.

```bash
yarn add zaileys
```

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

### Install storage adapter drivers with bun

Source: https://zeative.github.io/zaileys/runtimes

Installs specific database drivers for Zaileys storage adapters using bun. Choose the driver corresponding to your chosen backend.

```bash
bun add better-sqlite3
bun add pg
bun add redis
```

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

### Install SQLite Driver with bun

Source: https://zeative.github.io/zaileys/troubleshooting

Install the 'better-sqlite3' driver using bun if you are using the SQLite auth/store adapter.

```bash
bun add better-sqlite3       # or: pg | redis | convex
```

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

### Complete Bot Example with Middleware and Commands

Source: https://zeative.github.io/zaileys/commands

A full example of a Zaileys bot including logging middleware and multiple commands like ping, help, and weather. It demonstrates setting up the client, event listeners, and command handlers.

```typescript
import { Client, type Middleware } from 'zaileys'
 
const client = new Client({ commandPrefix: ['/', '!'] })
 
client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))
 
const loggingMiddleware: Middleware = async (ctx, next) => {
  console.log(`[command] ${ctx.command} from ${ctx.senderId} args=${ctx.args.join(',')}`)
  await next()
}
 
client.use(loggingMiddleware)
 
client.command('ping', async (ctx) => {
  await ctx.reply('pong')
})
 
client.command('help|h|?', async (ctx) => {
  await ctx.reply('Commands: /ping, /weather <city>, /help')
})
 
client.command('weather', async (ctx) => {
  const city = ctx.args[0]
  if (!city) {
    await ctx.reply('Usage: /weather <city>')
    return
  }
  await ctx.reply(`Weather in ${city}: sunny, 28 degrees`)
})
 
client.on('connect', ({ me }) => {
  console.log('Command bot ready as', me.id)
})
```

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

### Initializing Zaileys Client in CommonJS

Source: https://zeative.github.io/zaileys/runtimes

Example of initializing the Client with pairing authentication in a CommonJS project.

```javascript
const { Client } = require('zaileys')

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

client.on('connection', ({ status }) => console.log(status))
client.connect()
```

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

### Install Zaileys using pnpm

Source: https://zeative.github.io/zaileys/installation

Use this command to install the Zaileys package with pnpm.

```bash
pnpm add zaileys
```

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

### Install better-sqlite3 for SQLite Storage

Source: https://zeative.github.io/zaileys/storage

Install the 'better-sqlite3' package to enable SQLite storage for authentication and message history.

```bash
npm i better-sqlite3
```

```bash
pnpm add better-sqlite3
```

```bash
yarn add better-sqlite3
```

```bash
bun add better-sqlite3
```

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

### Install pg for PostgreSQL Storage

Source: https://zeative.github.io/zaileys/storage

Install the 'pg' package to enable PostgreSQL storage for authentication and message history.

```bash
npm i pg
```

```bash
pnpm add pg
```

```bash
yarn add pg
```

```bash
bun add pg
```

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

### Install Sharp Image Accelerator with Yarn

Source: https://zeative.github.io/zaileys/installation

Install the 'sharp' package, an optional native accelerator for image processing, using Yarn.

```bash
yarn add sharp
```

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

### Install Zaileys Database Adapters with Bun

Source: https://zeative.github.io/zaileys/installation

Install adapters for SQLite, PostgreSQL, Redis, and Convex using Bun. For pnpm, you might need to approve build scripts.

```bash
bun add better-sqlite3   # SQLite adapters
bun add pg               # PostgreSQL adapters
bun add redis            # Redis adapters
bun add convex           # Convex adapters
```

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

### Install SQLite Driver with npm

Source: https://zeative.github.io/zaileys/troubleshooting

Install the 'better-sqlite3' driver using npm if you are using the SQLite auth/store adapter.

```bash
npm install better-sqlite3   # or: pg | redis | convex
```

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

### Install Sharp Image Accelerator with pnpm

Source: https://zeative.github.io/zaileys/installation

Install the 'sharp' package, an optional native accelerator for image processing, using pnpm.

```bash
pnpm add sharp
```

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

### Install storage adapter drivers with yarn

Source: https://zeative.github.io/zaileys/runtimes

Installs specific database drivers for Zaileys storage adapters using yarn. Choose the driver corresponding to your chosen backend.

```bash
yarn add better-sqlite3
yarn add pg
yarn add redis
```

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

### Install SQLite Driver with yarn

Source: https://zeative.github.io/zaileys/troubleshooting

Install the 'better-sqlite3' driver using yarn if you are using the SQLite auth/store adapter.

```bash
yarn add better-sqlite3      # or: pg | redis | convex
```

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

### Initializing Zaileys Client in ESM/TypeScript

Source: https://zeative.github.io/zaileys/runtimes

Example of initializing the Client with pairing authentication in an ESM or TypeScript project.

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

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

client.on('connection', ({ status }) => console.log(status))
await client.connect()
```

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

### Install SQLite Driver with pnpm

Source: https://zeative.github.io/zaileys/troubleshooting

Install the 'better-sqlite3' driver using pnpm if you are using the SQLite auth/store adapter.

```bash
pnpm add better-sqlite3      # or: pg | redis | convex
```

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

### Full Rich Response Example

Source: https://zeative.github.io/zaileys/rich-responses

A comprehensive example demonstrating various markdown features like bold text, links, code blocks, tables, and metadata like title, footer, and sources.

```javascript
await client.send('628xxx@s.whatsapp.net').text(
  [
    '*Daily brief* ☕',
    '',
    'Repo: [GitHub](https://github.com/zeative/zaileys)',
    'A citation: [](https://github.com/zeative/zaileys)',
    '',
    '```ts',
    "const client = new Client()",
    '```',
    '',
    '| Feature | Status |',
    '|---|---|
    '| Buttons | Ready |',
    '| AIRich  | Experimental |',
  ].join('\n'),
  {
    rich: true,
    title: '📰 zaileys Daily',
    footer: '💡 Dibuat dengan zaileys — github.com/zeative/zaileys',
    sources: [
      ['https://avatars.githubusercontent.com/u/9919?s=64', 'https://github.com/zeative/zaileys', 'zaileys on GitHub'],
    ],
  },
)
```

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

### Complete Echo Bot Example

Source: https://zeative.github.io/zaileys/getting-started

A full example of an echo bot that handles connection lifecycle events and replies to text messages.

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

const client = new Client({
  sessionId: 'echo-bot', // names the auth folder + log line
})

client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))

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

client.on('disconnect', ({ reason, willReconnect }) => {
  console.log('Disconnected:', reason, willReconnect ? '(reconnecting)' : '')
})

client.on('text', async (msg) => {
  console.log('Received from', msg.senderId, '|', msg.text)
  await msg.reply(`Hello ${msg.senderName ?? ''}! You said: ${msg.text}`)
})
```

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

### Initialize Client with SQLite Message Store and Query History

Source: https://zeative.github.io/zaileys/storage

This example demonstrates initializing the Zaileys client with a SQLite message store and then querying for recent messages, chats, and contacts after the client connects. It shows how to access paginated chat history.

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

const store = new SqliteMessageStore({ database: './history.db' })
const client = new Client({ store })

client.on('connect', async () => {
  // newest-first, paginated chat history for one JID
  const recent = await store.listMessages('628123456789@s.whatsapp.net', { limit: 50 })
  console.log(`loaded ${recent.length} messages`)

  const chats = await store.listChats({ archived: false })
  const contacts = await store.listContacts()
  console.log(chats.length, 'chats,', contacts.length, 'contacts')
})
```

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

### Importing Zaileys in Deno using npm specifier

Source: https://zeative.github.io/zaileys/runtimes

Example of importing the Client in Deno using the npm specifier, assuming dependencies are cached.

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

const client = new Client({ authType: 'qr' })
await client.connect()
```

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

### Deploy Convex Functions

Source: https://zeative.github.io/zaileys/storage

Deploy the necessary Convex functions for the adapter to work. This command starts the local development server or deploys to production.

```bash
npx convex dev   # or: npx convex deploy
```

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

### Install Node.js and build tools on Termux

Source: https://zeative.github.io/zaileys/runtimes

Installs Node.js LTS, Python, Make, Clang, and FFmpeg on Termux. These are required for compiling native modules and for media processing.

```bash
pkg update && pkg upgrade
pkg install nodejs-lts python make clang ffmpeg
```

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

### Installing Zaileys dependencies for Deno

Source: https://zeative.github.io/zaileys/runtimes

Command to cache Zaileys and its npm dependencies into a local node_modules directory for Deno.

```bash
deno cache --node-modules-dir npm:zaileys
```

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

### Install and Run TypeScript with tsx using npm

Source: https://zeative.github.io/zaileys/installation

Install tsx as a development dependency and use it to run TypeScript files directly. This avoids a separate build step during development.

```bash
npm i -D tsx
npx tsx bot.ts
```

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

### Install and Run TypeScript with tsx using pnpm

Source: https://zeative.github.io/zaileys/installation

Install tsx as a development dependency and use it to run TypeScript files directly with pnpm. This avoids a separate build step during development.

```bash
pnpm add -D tsx
pnpm tsx bot.ts
```

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

### Command Router with Middleware

Source: https://zeative.github.io/zaileys

Set up a command router with custom prefixes and middleware for handling commands. Includes an example of a logging middleware.

```typescript
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>')
})
```

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

### Use a Middleware for Command Processing

Source: https://zeative.github.io/zaileys/api-reference

Implement a middleware function that runs before command handlers. This example logs the detected command.

```javascript
client.use(async (ctx, next) => { console.log(ctx.command); await next() })
```

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

### Manual Connection Setup

Source: https://zeative.github.io/zaileys/client

Initializes the Zaileys client with auto-connection disabled. This requires manual invocation of the connect() method.

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

const client = new Client({ sessionId: 'manual', autoConnect: false })
```

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

### Media Processing with Zaileys

Source: https://zeative.github.io/zaileys/api-reference

Instantiate the Media class to process audio and video files. This example shows how to convert an audio file to Opus format and generate a video thumbnail.

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

const m = new Media('./input.mp3')
const opus = await m.audio.toOpus()
const thumb = await m.video.thumbnail()
```

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

### Zaileys Smoke Test File

Source: https://zeative.github.io/zaileys/installation

Create a TypeScript file to verify Zaileys installation by checking if the Client can be imported and constructed. This example uses 'autoConnect: false' for a no-side-effects test.

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

const client = new Client({ autoConnect: false })

console.log('zaileys loaded:', typeof Client === 'function')
console.log('client constructed:', client instanceof Client)

// When you are ready to go online, start the connection explicitly:
// await client.connect()
// client.on('qr', ({ qrString }) => console.log(qrString))
```

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

### Construct Media from Various Inputs

Source: https://zeative.github.io/zaileys/media

Demonstrates creating Media instances from different input types: URL, file path, and Buffer. Ensure necessary modules like 'node:fs/promises' are imported for file system operations.

```javascript
import { Media } from 'zaileys'
import fs from 'node:fs/promises'

const fromUrl = new Media('https://example.com/voice.mp3')
const fromPath = new Media('./assets/photo.jpg')
const fromBuffer = new Media(await fs.readFile('./assets/clip.mp4'))
```

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

### Connect the Client

Source: https://zeative.github.io/zaileys/interactive

Initializes a new `Client` instance and sets up a listener for the 'qr' event to display the QR code for authentication.

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

const client = new Client()
client.on('qr', ({ qrString }) => console.log('Scan QR:', qrString))
```

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

### Send a Text Message with Reply

Source: https://zeative.github.io/zaileys/api-reference

Construct and send a text message using the fluent builder pattern. This example shows how to set the recipient, message content, and reply to a specific message.

```javascript
client
  .send('628xxx@s.whatsapp.net')
  .text('Hello *world*')
  .reply(msg.message().key)
```

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

### Constructing a Media Instance

Source: https://zeative.github.io/zaileys/media

Import `Media` from `zaileys` and pass your input source to the constructor. The input can be a URL, a file path, a base64 string, a Buffer, or an ArrayBuffer. The processing is lazy and only occurs when a method is called.

```APIDOC
## Constructing a `Media`

Import `Media` from `zaileys` and pass it your source once — every namespace below operates on that same input.

```javascript
import { Media } from 'zaileys'
 
const media = new Media(input)
```

The constructor accepts a single `MediaInput`, which is one of:

Input type| Example| Notes  
---|---|---  
`string` URL| `'https://example.com/song.mp3'`| Fetched over HTTP(S) with the global `fetch`.  
`string` path| `'./assets/clip.mp4'`| Read from disk if the path points to an existing file.  
`string` b64| `'iVBORw0KGgo...'`| Falls back to base64 decoding when it is neither URL nor file.  
`Buffer`| `await fs.readFile('./img.png')`| Used as-is.  
`ArrayBuffer`| `await res.arrayBuffer()`| Wrapped into a `Buffer`.

```javascript
import { Media } from 'zaileys'
import fs from 'node:fs/promises'
 
const fromUrl = new Media('https://example.com/voice.mp3')
const fromPath = new Media('./assets/photo.jpg')
const fromBuffer = new Media(await fs.readFile('./assets/clip.mp4'))
```

Resolution is lazy. Nothing is downloaded or read until you call a processing method, so constructing a `Media` is cheap. The same instance can be reused across namespaces — for example call both `media.thumbnail.get()` and `media.image.toJpeg()` on one `Media`.
```

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

### Import and Construct Media Instance

Source: https://zeative.github.io/zaileys/media

Import the Media class from 'zaileys' and create a new instance by passing the input source. The input can be a URL, file path, base64 string, Buffer, or ArrayBuffer. Construction is lazy, with processing occurring only when a method is called.

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

const media = new Media(input)
```

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

### Initialize Client with SqliteAuthStore

Source: https://zeative.github.io/zaileys/api-reference

Instantiate the Zaileys client with a session ID and a SQLite-backed authentication store. Ensure the 'zaileys' package is imported.

```javascript
import { Client, SqliteAuthStore } from 'zaileys' 

const client = new Client({
  sessionId: 'main',
  auth: new SqliteAuthStore({ path: './session.db' }),
})
```

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

### Register Commands and Middleware

Source: https://zeative.github.io/zaileys/client

Set up command handlers and global middleware using `client.use()` and `client.command()`. Commands are activated when `commandPrefix` is set.

```javascript
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)
  .command('ping', async (ctx) => {
    await ctx.reply('pong')
  })
  .command('help|h|?', async (ctx) => {
    await ctx.reply('Commands: /ping, /help')
  })
```

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

### Multiple Client Instances with Unique Session IDs

Source: https://zeative.github.io/zaileys/configuration

Demonstrates initializing multiple client instances, each with a unique sessionId. This is crucial for managing multiple accounts as it ensures distinct authentication folders and event identification.

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

const primary = new Client({ sessionId: 'account-a' })
const secondary = new Client({ sessionId: 'account-b' })

primary.on('connect', ({ sessionId, me }) => console.log(sessionId, 'ready as', me.id))
secondary.on('connect', ({ sessionId, me }) => console.log(sessionId, 'ready as', me.id))

```

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

### Enable Commands with Client Options

Source: https://zeative.github.io/zaileys/commands

Set the `commandPrefix` option in the `Client` constructor to enable the command framework. This can be a single string or an array of strings.

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

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

// Multiple prefixes — any of them triggers a command
const multi = new Client({ commandPrefix: ['/', '!', '.'] })
```

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

### Command Framework with Prefix and Middleware

Source: https://zeative.github.io/zaileys/configuration

Enable the command framework by setting a command prefix and use middleware for logging commands. This snippet demonstrates setting multiple prefixes and a logging middleware.

```javascript
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) => {
  await ctx.reply('pong')
})
```

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

### Setting Up Connection Event Listeners

Source: https://zeative.github.io/zaileys/client

Attaches event listeners for 'qr' and 'connect' events before establishing a connection. This ensures listeners are active when the connection events fire.

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

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

### Install and Run TypeScript with tsx using yarn

Source: https://zeative.github.io/zaileys/installation

Install tsx as a development dependency and use it to run TypeScript files directly with yarn. This avoids a separate build step during development.

```bash
yarn add -D tsx
yarn tsx bot.ts
```

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

### Basic Hello World Bot

Source: https://zeative.github.io/zaileys

A complete, working bot that connects, prints a QR code for authentication, and echoes incoming text messages back to the sender. It demonstrates event handling for 'qr', 'connect', and 'text' events.

```typescript
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) => {
  const quoted = await msg.replied()
  if (quoted) console.log('In reply to:', quoted.senderId, '|', quoted.text)
 
  await msg.reply(`Hello ${msg.senderName ?? ''}! You said: ${msg.text}`)
})
```

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

### Constructing a Zaileys Client

Source: https://zeative.github.io/zaileys/client

Instantiate the Client with a session ID and set up an event listener for connection events. By default, the client attempts to connect automatically upon construction.

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

const client = new Client({ sessionId: 'default' })

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

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

### Get Group Metadata

Source: https://zeative.github.io/zaileys/api-reference

Retrieve metadata for a specific group using its ID. Ensure the group ID is correctly formatted.

```javascript
const meta = await client.group.metadata('xxx@g.us')
```

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

### Initialize Client with Memory Stores

Source: https://zeative.github.io/zaileys/api-reference

Instantiate the `Client` using in-memory stores for authentication and messages. This is useful for testing or scenarios where persistence is not required. The client listens for 'connection' and 'message' events.

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

const client = new Client({
  sessionId: 'main',
  auth: new MemoryAuthStore(),
  store: new MemoryMessageStore(),
  authType: 'qr',
  qrTerminal: true,
})

client.on('connection', (s) => console.log(s.status))
client.on('message', (msg) => {
  if (msg.text() === 'ping') client.send(msg.chatId()).text('pong')
})
```

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

### Register a Command Handler

Source: https://zeative.github.io/zaileys/api-reference

Define a command handler for a specific command string. This example registers a 'ping' command that replies with 'pong'.

```javascript
client.command('ping', async (ctx) => ctx.reply('pong'))
```

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

### Configuring Client with Manual Connection and Reconnection Options

Source: https://zeative.github.io/zaileys/client

Construct a client with a specific session ID, QR login, ignoring self-sent messages, and custom reconnection settings. This configuration allows for manual connection control and tuned reconnection behavior.

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

const client = new Client({
  sessionId: 'support-bot',
  authType: 'qr',
  ignoreMe: true,
  reconnect: { maxAttempts: 10, initialDelayMs: 2000, maxDelayMs: 30_000 },
})
```

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

### Send Contact (vCard)

Source: https://zeative.github.io/zaileys/sending-messages

Send a contact card using a raw vCard string. The string must start with `BEGIN:VCARD`.

```APIDOC
## Contact (vCard)
Send a contact card. Pass a raw vCard string — it must start with `BEGIN:VCARD`.
```

const vcard = [
  'BEGIN:VCARD',
  'VERSION:3.0',
  'FN:Zaileys Bot',
  'TEL;type=CELL;type=VOICE;waid=6281234567890:+62 812-3456-7890',
  'END:VCARD',
].join('\n')
 
await client.send(to).contact(vcard)
```

`contact()` takes the vCard string directly (no options object). A string that does not begin with `BEGIN:VCARD` rejects with `INVALID_OPTIONS`.
```

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

### Send Contact (vCard)

Source: https://zeative.github.io/zaileys/sending-messages

Send a contact card by providing a raw vCard string. The string must start with 'BEGIN:VCARD'.

```javascript
const vcard = [
  'BEGIN:VCARD',
  'VERSION:3.0',
  'FN:Zaileys Bot',
  'TEL;type=CELL;type=VOICE;waid=6281234567890:+62 812-3456-7890',
  'END:VCARD',
].join('\n')

await client.send(to).contact(vcard)
```

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

### Convert Media to Buffer

Source: https://zeative.github.io/zaileys/media

Use `toBuffer()` to get the raw bytes of a media source. This is useful for downloading files or reading them once for repeated use.

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

const buffer = await new Media('https://example.com/file.bin').toBuffer()
```

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

### connect()

Source: https://zeative.github.io/zaileys/client

Opens the WhatsApp socket and resolves when the connection is established. If no stored credentials exist, it triggers the QR code or pairing code flow.

```APIDOC
### `connect()`

```typescript
connect(): Promise<void>
```

Opens the WhatsApp socket and resolves once the connection is **open** (`'connect'` event fired). If the session has no stored credentials, this is when the QR or pairing code is produced.
```

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

### Run Bot with bun

Source: https://zeative.github.io/zaileys/getting-started

Execute your bot script using the bun runtime.

```bash
bun run bot.ts
```

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

### Rich Reply Example

Source: https://zeative.github.io/zaileys/rich-responses

Demonstrates sending a rich reply message. The 'reply' method accepts the same options as 'sendText', including rich content and directives.

```typescript
client.on('text', async (msg) => {
  if (msg.text.trim().toLowerCase() === 'rich') {
    await msg.reply(
      [
        '*Rich reply example* ✨',
        '',
        '```ts',
        'const x = 1',
        '```',
        '',
        ':::suggest',
        'Again | Close',
        ':::',
      ].join('\n'),
      { rich: true, title: '🤖 zaileys' },
    )
  }
})
```

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

### Handling ZaileysBuilderError

Source: https://zeative.github.io/zaileys/api-reference

Catch and handle specific Zaileys builder errors. This example demonstrates how to check if an error is an instance of ZaileysBuilderError and log its code and message.

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

try {
  await client.send(jid).text('hi')
} catch (e) {
  if (e instanceof ZaileysBuilderError) console.error(e.code, e.message)
}
```

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

### Disable Auto-Connect

Source: https://zeative.github.io/zaileys/configuration

Set `autoConnect` to `false` to manually control the connection process. This allows registering listeners or performing setup before explicitly calling `client.connect()`.

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

const client = new Client({ autoConnect: false })

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

await client.connect()
```

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

### Convex Adapter with Pre-built Client

Source: https://zeative.github.io/zaileys/storage

Configure the Convex adapter using a pre-built Convex client. This is useful if you already have a client instance.

```typescript
import { ConvexHttpClient } from 'convex/browser'
import { ConvexAuthStore, ConvexMessageStore } from 'zaileys'

const convex = new ConvexHttpClient(process.env.CONVEX_URL!)
const auth = new ConvexAuthStore({ client: convex, namespace: 'wa-auth' })
const store = new ConvexMessageStore({ client: convex, namespace: 'wa-store' })
```

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

### Mixing PostgresAuthStore and RedisMessageStore

Source: https://zeative.github.io/zaileys/storage

This setup is ideal for durable authentication in Postgres and fast message history retrieval from Redis. You are responsible for managing the Redis client lifecycle.

```typescript
import { Pool } from 'pg'
import { createClient } from 'redis'
import { Client, PostgresAuthStore, RedisMessageStore } from 'zaileys'

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
const redis = createClient({ url: 'redis://localhost:6379' })
await redis.connect()

// Durable auth in Postgres, fast history in Redis
const client = new Client({
  auth: new PostgresAuthStore({ pool }),
  store: new RedisMessageStore({ client: redis, namespace: 'wa-store' }),
})
```

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

### Running a Bun application

Source: https://zeative.github.io/zaileys/runtimes

Command to execute a TypeScript bot file directly using Bun.

```bash
# Bun runs .ts files directly
bun run bot.ts
```
Tokens:
Raw