Commands

Zaileys ships a small but capable command framework on top of the message pipeline. Set a commandPrefix in your client options, register handlers with client.command(), and each matching message is parsed into a typed context with positional arguments, flags, JSON payloads, and reply helpers.

Enabling commands

The framework is off by default. It only activates when you pass commandPrefix to the Client constructor. The option accepts a single prefix string or an array of prefixes.

import { Client } from 'zaileys'
 
// Single prefix
const client = new Client({ commandPrefix: '/' })
 
// Multiple prefixes — any of them triggers a command
const multi = new Client({ commandPrefix: ['/', '!', '.'] })

Commands are matched on the text event stream, so they work in DMs, groups, and any chat that produces a text message. See Events for the full event surface.

Registering a command

Use client.command(name, handler). The handler receives a single ctx argument and may be sync or async. command() returns the client, so calls are chainable.

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

With commandPrefix: ['/', '!'], both /ping and !ping invoke this handler.

Aliases

Separate alternative names with a pipe (|). The first segment is the canonical name (the value you receive in ctx.command); the rest are aliases that resolve to the same handler.

client.command('help|h|?', async (ctx) => {
  await ctx.reply('Commands: /ping, /weather <city>, /help')
})

Now /help, /h, and /? all run the handler, and ctx.command is always 'help'.

Multi-word commands

A single segment may contain spaces, which registers a multi-word (sub)command. Resolution prefers the longest match, so you can layer specific subcommands over a general one.

client.command('group info', async (ctx) => {
  await ctx.reply('Group subcommand: info')
})
 
client.command('group kick', async (ctx) => {
  await ctx.reply(`Kicking: ${ctx.args.join(', ')}`)
})

/group kick 628123 resolves to group kick with ctx.args === ['628123']. The leading words that form the command name are consumed and never appear in ctx.args.

The command context

A CommandContext extends the full message context — every field and method from a normal text message is available (ctx.senderId, ctx.roomId, ctx.isGroup, ctx.message(), ctx.replied(), and so on). On top of that base, the command framework adds the following:

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

Because the context inherits everything from the message context, you can branch on the chat:

client.command('whoami', async (ctx) => {
  if (ctx.isGroup) {
    await ctx.reply(`You are ${ctx.senderId} in room ${ctx.roomId}`)
    return
  }
  await ctx.reply(`You are ${ctx.senderId} (${ctx.senderName ?? 'unknown'})`)
})

client.command('progress', async (ctx) => {
  await ctx.reply('Working...')
  // ...do something...
  await ctx.edit('Done.')
})

Argument parsing

When a message matches a prefix, the text after the prefix is tokenized. The parser is quote- and flag-aware. Understanding the rules helps you design predictable commands.

Tokenization

• Whitespace separates tokens.
• Double (") or single (') quotes group a token, so /say "hello world" yields one argument hello world. Quotes are only treated as openers at the start of a token.
• Inside quotes, \ escapes the next character (e.g. "a\"b" → a"b).
• The first token is the command name (lowercased); the rest are candidate args/flags.

client.command('say', async (ctx) => {
  // /say "hello world" loud  ->  args = ['hello world', 'loud']
  await ctx.reply(ctx.args.join(' | '))
})

Flags

Tokens starting with -- become entries in ctx.flags:

client.command('deploy', async (ctx) => {
  // /deploy app1 --env=prod --force
  const target = ctx.args[0]          // 'app1'
  const env = ctx.flags.env           // 'prod'
  const force = ctx.flags.force === true
  await ctx.reply(`Deploy ${target} to ${env}${force ? ' (forced)' : ''}`)
})

JSON arguments

The first token that begins with { or [ and parses as valid JSON is exposed on ctx.json. The token also remains in ctx.args (JSON parsing is additive, not consuming). Invalid JSON is left untouched and simply stays an arg.

client.command('config', async (ctx) => {
  // /config {"theme":"dark","notify":true}
  const cfg = ctx.json as { theme: string; notify: boolean } | undefined
  if (!cfg) {
    await ctx.reply('Send a JSON object: /config {"theme":"dark"}')
    return
  }
  await ctx.reply(`Theme set to ${cfg.theme}`)
})

Middleware

Register middleware with client.use(middleware). Each middleware has the signature (ctx, next) => void | Promise<void> and runs before the matched command handler — ideal for logging, authentication, and rate limiting. Like command(), use() returns the client and is chainable.

import { Client, type Middleware } from 'zaileys'
 
const client = new Client({ commandPrefix: ['/', '!'] })
 
const loggingMiddleware: Middleware = async (ctx, next) => {
  console.log(`[command] ${ctx.command} from ${ctx.senderId} args=${ctx.args.join(',')}`)
  await next()
}
 
client.use(loggingMiddleware)

Ordering and the onion model

Middleware runs in registration order, wrapping the handler like layers of an onion. Call next() to pass control to the next middleware (and eventually the handler); skip next() to short-circuit and stop the chain.

// 1. Outermost: timing
client.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  console.log(`${ctx.command} took ${Date.now() - start}ms`)
})
 
// 2. Auth gate — short-circuits unauthorized callers
const ADMINS = ['628123@s.whatsapp.net']
client.use(async (ctx, next) => {
  if (!ADMINS.includes(ctx.senderId)) {
    await ctx.reply('Not authorized.')
    return // do NOT call next() — handler never runs
  }
  await next()
})
 
// 3. Handler runs only if both middlewares called next()
client.command('shutdown', async (ctx) => {
  await ctx.reply('Shutting down...')
})

For /shutdown, the execution order is: timing (before next) → auth → handler → timing (after next). If the auth middleware returns without calling next(), the handler and the rest of the chain are skipped, but the timing middleware’s “after” code still runs because it already awaited next().

Error handling in the chain

Errors thrown by middleware or handlers are caught by the dispatcher and logged via the client logger; they do not crash the process. Non-ZaileysCommandError throws are wrapped: a handler failure becomes a HANDLER_ERROR, and a middleware failure becomes a MIDDLEWARE_ERROR. See Error handling for the full error model.

client.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    await ctx.reply('Something went wrong.')
    throw err // re-throw so the client logger still records it
  }
})

A complete bot

This mirrors examples/command-bot.ts — a small router with logging middleware and a few commands.

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

Edge cases & gotchas

Types reference

All command types are exported from zaileys:

import type {
  CommandContext,
  CommandHandler,
  Middleware,
  CommandPrefix,
  ParsedArgs,
} from 'zaileys'

Related

• Configuration — commandPrefix, autoConnect, and other client options.
• Events — the text event and the full message context that commands inherit.
• Sending messages — TextOptions accepted by ctx.reply().
• Error handling — ZaileysCommandError codes and the dispatcher’s error model.