Broadcast & Schedule

Zaileys ships a small automation toolkit on top of the regular message builder: send the same message to many recipients with built-in rate limiting (client.broadcast), queue a message for a future moment (client.scheduleAt), and drive typing/online indicators (client.presence). Every one of these reuses the same builder you already know from Sending Messages, so anything you can send normally you can broadcast or schedule.

Broadcast

client.broadcast() sends one message to a list of recipients, pacing the sends through a token bucket so you never exceed WhatsApp’s tolerances. The builder callback runs once per recipient, giving you a fresh builder bound to that recipient’s JID.

import { Client } from 'zaileys'
 
const client = new Client()
 
client.on('connect', async () => {
  const result = await client.broadcast(
    ['6281111111111@s.whatsapp.net', '6282222222222@s.whatsapp.net'],
    (builder) => builder.text('Announcement: maintenance tonight at 22:00.'),
    { rateLimitPerSec: 5 },
  )
 
  console.log(`Sent ${result.sent.length}, failed ${result.failed.length}`)
})

Signature

broadcast(
  jids: string[],
  build: (b: MessageBuilder) => MessageBuilder,
  options?: BroadcastOptions,
): Promise<BroadcastResult>

Options

The onProgress callback signature is exactly:

onProgress: (done: number, total: number, jid: string, ok: boolean) => void

• done — how many recipients have been processed so far (1-based, increments on success and failure).
• total — total number of recipients (jids.length).
• jid — the recipient that was just processed.
• ok — true if the send succeeded, false if it failed.

const result = await client.broadcast(
  recipients,
  (b) => b.text('Promo: 20% off all items this weekend.'),
  {
    rateLimitPerSec: 5,
    onProgress: (done, total, jid, ok) => {
      console.log(`[${done}/${total}] ${jid} ${ok ? 'sent' : 'failed'}`)
    },
  },
)

Result shape

broadcast() resolves to a BroadcastResult once every recipient has been attempted. It never rejects on per-recipient failures — failed sends are collected, not thrown.

type BroadcastResult = {
  sent: string[]                              // JIDs that succeeded
  failed: { jid: string; error: Error }[]     // JIDs that failed, with the original error
}

const { sent, failed } = await client.broadcast(recipients, (b) => b.text('Hello!'))
 
console.log(`${sent.length} delivered`)
for (const f of failed) {
  console.error(`Failed ${f.jid}: ${f.error.message}`)
}

Any builder content works

The builder passed to broadcast() is the full message builder — text is just the simplest case. You can send media, captions, mentions, buttons, or anything else the builder supports.

await client.broadcast(
  recipients,
  (b) =>
    b.image('https://example.com/banner.jpg', {
      caption: 'New collection is live!',
    }),
  { rateLimitPerSec: 3 },
)

Rate limiting (token bucket)

Broadcasts are paced by an internal token-bucket rate limiter. Conceptually:

• The bucket starts full with rateLimitPerSec tokens (this is also the burst capacity).
• It refills continuously at rateLimitPerSec tokens per second.
• Each recipient consumes one token before its send. If no token is available, the broadcast awaits just long enough for one to refill, then proceeds.

This means an initial burst can go out immediately (up to the bucket capacity), after which sends settle into a steady rateLimitPerSec cadence — no manual sleep() calls required.

// At most ~2 messages per second, smoothing out a 500-recipient blast.
await client.broadcast(bigList, (b) => b.text('Newsletter #42'), {
  rateLimitPerSec: 2,
})

import { RateLimiter } from 'zaileys'
 
const limiter = new RateLimiter({ perSec: 10, perJidPerSec: 1, burst: 20 })
await limiter.acquire('6281111111111@s.whatsapp.net') // waits if needed

Retry & error handling

By default, broadcast does not retry — a failed recipient simply lands in result.failed with its original Error. The run never aborts because one JID is bad; every recipient is attempted independently.

To retry transient failures, pass a retry policy. When set, each recipient’s send is wrapped in a serial queue (concurrency 1) that re-runs the send up to maxRetries times, sleeping backoffMs(attempt) milliseconds between attempts. A recipient only counts as failed after all retries are exhausted.

type RetryPolicy = {
  maxRetries: number
  backoffMs: (attempt: number) => number   // attempt is 1-based
}

await client.broadcast(
  recipients,
  (b) => b.text('Important notice'),
  {
    rateLimitPerSec: 5,
    retry: {
      maxRetries: 3,
      backoffMs: (attempt) => attempt * 1000, // 1s, 2s, 3s
    },
  },
)

Schedule

client.scheduleAt() queues a message to be sent at a future Date. Critically, the builder callback is evaluated once, at schedule time, into a serializable snapshot ({ recipient, content, options? }) — it is never stored as a live closure. That snapshot is what gets persisted and replayed, which is exactly what makes restart-recovery possible.

import { Client } from 'zaileys'
 
const client = new Client()
 
client.on('connect', async () => {
  const job = await client.scheduleAt(
    new Date(Date.now() + 60_000), // one minute from now
    (b) => b.to('6281111111111@s.whatsapp.net').text('This sends in one minute.'),
  )
 
  console.log('Scheduled job id:', job.id)
})

Signature

scheduleAt(
  date: Date,
  build: (b: MessageBuilder) => MessageBuilder,
): Promise<ScheduleHandle>

The returned ScheduleHandle:

type ScheduleHandle = {
  id: string        // unique job id (UUID)
  cancel(): void    // cancel before it fires; removes it from the store too
}

const job = await client.scheduleAt(date, (b) => b.to(jid).text('Reminder'))
 
// Changed your mind before it fires:
job.cancel()

Persistence & restart recovery

Each scheduled job is timed in-process with a timer and, when supported, persisted to the message store. On startup the client automatically calls the scheduler’s loadPending() to re-arm any jobs that were saved but had not yet fired — so a job scheduled for 3am survives a restart at midnight.

Restart-survival depends on the store implementing the optional scheduled-job methods:

When a job fires, the snapshot is dispatched through the live socket. If the send fails at fire time, the error is logged via the client logger (it does not crash the process), and the job is removed from the store.

Presence automation

client.presence exposes typing, recording, and online/offline indicators. It is a lazily-created PresenceModule and requires an active connection (it throws ZaileysAutomationError with code NOT_CONNECTED otherwise).

import { Client } from 'zaileys'
 
const client = new Client()
const jid = '6281111111111@s.whatsapp.net'
 
client.on('connect', async () => {
  await client.presence.online() // mark account as online
 
  await client.presence.typing(jid)   // show "typing…" in that chat
  await client.send(jid).text('Hi! Thanks for waiting.')
})

Methods

// Simulate a natural typing delay before replying.
await client.presence.typing(jid, 2000) // auto-clears after 2s
setTimeout(() => client.send(jid).text('Done thinking!'), 2000)

Errors

Automation-specific failures throw ZaileysAutomationError, which carries a code and an optional cause. You can import it from zaileys to handle these precisely.

import { Client, ZaileysAutomationError } from 'zaileys'
 
try {
  await client.presence.online()
} catch (err) {
  if (err instanceof ZaileysAutomationError && err.code === 'NOT_CONNECTED') {
    console.error('Connect the client before driving presence.')
  }
}