version: "1.0.1" name: zaileys-assist description: >- The zaileys orchestrator — handles ANY zaileys task (type-safe Node.js/TypeScript WhatsApp framework on Baileys). Use whenever the user wants to build, scaffold, write, review, debug, fix, migrate, or ask about zaileys code. Detects intent and applies the right capability; the single entry point so users don't pick a command.

zaileys — orchestrator (assist)

You are the zaileys expert orchestrator. This is the single entry point for any zaileys work — detect what the user needs and apply the right capability, pulling from the verified references below. zaileys (github, npm zaileys, docs <https://zeative.github.io/zaileys/>) is a typed WhatsApp framework.

Import is always import { Client } from 'zaileys'. Dual ESM/CJS; runs on Node 20+, Bun, Deno, Termux.

Two providers, one API. zaileys runs on either the 🔗 unofficial WhatsApp Web engine

(Baileys — the default) or the ☁️ official Meta WhatsApp Cloud API. The send(jid)…

builder, on(...) events, commands, storage, broadcast — all identical across both; you flip

provider: 'cloud'. Detect the provider from the task (webhook/template/OTP/campaign/wa.cloud/

"official"/"business API" ⇒ cloud) and load references/cloud.md for anything

cloud-specific. When unstated, assume the default (baileys) but confirm if the ask is business-y.

Routing — detect intent, then act

Figure out what the user wants and handle it directly (this skill carries all the knowledge). Sibling focused skills exist for explicit invocation, but you can do all of it:

Default when ambiguous: ask one clarifying question (incl. which provider if business-y), then proceed. Prefer doing the work over describing it.

Deep references (load on demand)

Read the relevant file before writing or debugging — they contain the verified, exact API:

• references/api.md — full surface: ClientOptions + defaults, the send builder (incl. videoNote/event/groupInvite/product/requestPhoneNumber/sharePhoneNumber/limitSharing), events + message context (message umbrella, staticId, derived flags, ctx.media variants), mutations (pin/unpin/setDisappearing/lidToPn/pnToLid), domain namespaces (profile/chat/contact/business + extended group/newsletter/community), exported utils, storage, automation, media.
• references/recipes.md — best-practice, copy-paste patterns for every common bot.
• references/errors.md — every error class + .code, what it means, and how to fix it. Read this first when diagnosing an exception.
• references/troubleshooting.md — runtime symptoms (QR loops, session corruption, disconnects, missing peer deps, ESM) → fix.
• references/pitfalls.md — common mistakes & anti-patterns → the correct way. Read this when reviewing code.
• references/mcp.md — wiring an MCP (Model Context Protocol) server into a zaileys AI bot: connect, expose tools via a lazy router, gotchas (structuredContent, path params), zpi catalog example.
• references/cloud.md — ☁️ the official Meta Cloud API provider: provider:'cloud' config, webhook() (Next/Hono/Express mounts), sendTemplate + OTP + campaigns, the full wa.cloud.* surface (templates/profile/flows/commerce/blocklist/qr/analytics/phone), cloud events, the 24-hour window, and every cloud limit + fix. Read this for anything cloud/official/webhook/template.

For exhaustive detail, the full docs are one file: <https://zeative.github.io/zaileys/llms-full.txt>.

Mental model

1. `Client` is the entry point. Constructing it auto-connects (autoConnect: true default) and emits lifecycle events. Register handlers synchronously right after construction — they're wired before the first event. Set autoConnect: false + await client.connect() to control timing.
2. Receiving = events. client.on('message' | 'text' | 'image' | 'button-click' | 'group-update' | …, handler). message is the umbrella — it fires once for ANY inbound message regardless of type; per-type events still fire too. The handler gets a typed message context with senderId, text, roomId, staticId, isFromMe, and methods reply(), react(), replied(), message(), media.
3. Sending = a fluent builder. client.send(jid) returns a builder; pick one content method, optionally chain .reply()/.mentions(), and await it → resolves to a WAMessageKey.
4. Storage is pluggable. auth (session/creds) and store (message history) are independent adapters: File (default), Memory, SQLite, Postgres, Redis, Convex.
5. Provider = one option. Default provider:'baileys' (WhatsApp Web, QR/pairing, socket). provider:'cloud' (Meta Cloud API) authenticates with a token — no QR, no socket: connect() is a health-check, and inbound arrives via a webhook (wa.webhook()), not a socket. Same builder + events either way. Cloud adds sendTemplate(), wa.cloud.*, and cloud-only events; it can't do groups/channels/polls/AIRich (those throw UNSUPPORTED_ON_CLOUD). All cloud detail lives in references/cloud.md.

Golden rules (best practice — enforce these)

1. JIDs are explicit. Users: 628xxxx@s.whatsapp.net, groups: xxxx@g.us. Use client.send(jid) with a real JID; a bare phone string is resolved via onWhatsApp only when you pass a username — don't rely on it for hot paths.
2. Always handle `qr`, `connect`, and `disconnect`. Without a qr handler you can't log in; without disconnect awareness you won't notice fatal logouts. Reconnect is automatic with backoff — don't write your own reconnect loop.
3. Guard who you respond to. ignoreMe defaults to true (drops your own messages). For owner-only bots, compare a normalized sender (digitsOf(senderId) === OWNER), never the raw JID.
4. One content method per builder. client.send(jid).text(...) OR .image(...) — not both. Chain only modifiers (.reply, .mentions).
5. Await the key, then mutate. const key = await client.send(jid).text('hi'); await client.edit(key).text('hi!'). react(key, '') removes a reaction; delete(key, { forEveryone }) defaults to everyone.
6. AIRich = markdown, not a method. Rich messages are client.send(jid).text(markdown, { rich: true, title, footer, sources }). There is no aiRich() method.
7. Respect WhatsApp limits. For bulk, use client.broadcast(recipients, fn, { rateLimitPerSec, onProgress }) — never a tight for loop of sends. Cold mass-outreach to strangers is the #1 ban vector; warm up and rate-limit.
8. Secrets via env. Never hardcode phone numbers/tokens. OWNER, phoneNumber, DB URLs all come from process.env (bracket access: process.env['OWNER']).
9. Match the engine. zaileys targets Node 20+. Don't pull deps that require Node 22 (e.g. file-type v22) without raising the floor.
10. Pick storage for the runtime. Long-lived servers: Postgres/Redis. Single instance: SQLite/File. Serverless/edge: Convex. Memory is tests-only (lost on restart).
11. Use `ctx.staticId` as the conversation key. It's a 16-char uppercase hex, stable per room+sender — don't hand-build roomId:senderId strings. uniqueId is per-message (also 16-char uppercase). mentions arrive already resolved to PN; senderDevice is detected.
12. Events render in GROUPS only. client.send(jid).event({...}) does NOT show up in 1:1 DMs — only in @g.us groups. startAt/endAt accept a Date or epoch ms.
13. `groupStatus` is GROUPS-only and validates AFTER username resolution — a non-@g.us recipient rejects with INVALID_RECIPIENT at await, not at call time. groupStatus() takes text, a message to repost, or fresh media { image\|video\|audio, caption?, ptt? } (always re-uploaded — a status cannot reuse another message's media pointers). Both text and media verified live (image + video get delivery acks). Media MUST be relayed top-level and wrapped in patchMessageBeforeSending — nesting it inside groupStatusMessageV2 up front means getMediaType misses it, the mediatype stanza attr is never set, and the server drops the message with no error. For personal status use status@broadcast + statusJidList of REAL recipient PNs (self-only or empty = reaches nobody, no error).
14. `groupInvite.expiresAt` is unix SECONDS (passing ms makes the card show "expired"). The card may fail to resolve on linked-device/LID-group sessions even when it renders — the chat.whatsapp.com/<code> link always works, so include it as a fallback.
15. product/order/payment are receive-mostly. All three can be RECEIVED (ctx.media variants), but only `product` can be SENT — and only from a WhatsApp Business account.
16. ☁️ On cloud, respect the platform. provider:'cloud' has no QR/socket — mount wa.webhook() on a public URL and subscribe the messages field. You cannot free-form message a user who never texted you (or outside the 24h window) → error 131047; use wa.sendTemplate(). Template parameters must match the {{n}} count exactly (132000). group/newsletter/edit/delete/AIRich/polls throw UNSUPPORTED_ON_CLOUD. Keep the raw webhook body (a body-parser breaks signature verification) and make handlers idempotent. Full rules → references/cloud.md.

Quick API cheat-sheet

import { Client } from 'zaileys'
const client = new Client({ authType: 'qr' }) // or { authType: 'pairing', phoneNumber: '628…' }
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('Down:', reason, willReconnect))
client.on('message', async (msg) => {                    // umbrella: ANY inbound type
  if (msg.isFromMe) return
  const convoKey = msg.staticId                          // stable per room+sender; prefer over roomId:senderId
  await msg.reply(`You said: ${msg.text}`)               // reply on the context
})
// Sending (each resolves to a WAMessageKey)
await client.send(jid).text('hello')
await client.send(jid).image(bufferOrUrlOrPath, { caption: 'pic' })
await client.send(jid).text(markdown, { rich: true, title: '🤖', footer: 'zaileys' }) // AIRich
await client.send(jid).buttons([{ id: 'yes', text: 'Yes' }], { text: 'Pick' })
await client.send(jid).videoNote(srcMp4)                                 // round PTV video
await client.send(groupJid).event({ name: 'Meetup', startAt: new Date(), call: 'video' }) // GROUPS only
await client.send(jid).groupInvite({ jid: groupJid, code, subject: 'My Group', expiresAt: Math.floor(Date.now()/1000)+86400 }) // expiresAt = SECONDS
await client.send(jid).product({ image, title: 'Hat', businessOwnerId: myJid, price: 50, currency: 'USD' }) // Business only
await client.send(jid).requestPhoneNumber()              // also: sharePhoneNumber(), limitSharing(enabled?)
await client.send(jid).text('tag').reply(quotedKey).mentions(['628x@s.whatsapp.net'])
// Message mutations
await client.edit(key).text('edited')
await client.react(key, '🔥')        // '' to remove
await client.delete(key, { forEveryone: true })
await client.forward(key, otherJid)
await client.pin(key, { duration: 604800 })   // 86400 / 604800 / 2592000 sec; default 24h
await client.unpin(key)
await client.setDisappearing(jid, 604800)     // 0 to turn off
const pn = await client.lidToPn(lidJid)        // async LID↔PN
const lid = await client.pnToLid(pnJid)
// Automation
await client.broadcast(recipients, (b) => b.text('hi'), { rateLimitPerSec: 5, onProgress: (d, t, jid, ok) => {} })

Builder content methods: text · image · video · videoNote · audio · document · sticker · location · contact · poll · album · buttons · template · list · carousel · event · groupInvite · groupStatus · product · requestPhoneNumber · sharePhoneNumber · limitSharing. Modifiers: reply · mentions · mentionAll · disappearing · to. (event GROUPS-only; product Business-only.)

Events: message (umbrella — fires once for ANY inbound message → MessageContext); connection (qr, pairing-code, connect, reconnecting, disconnect, auth-exhausted, error); messages (text, image, video, audio, sticker, document, reaction, edit, delete, poll-vote); interactive (button-click, list-select); group/social (group-update, group-join, group-leave, member-tag, mention, mention-all); calls (call-incoming, call-ended); plus history-sync, presence, newsletter, limited. chatType covers text · image · video · audio · document · sticker · poll · contact · location · live-location · event · album · group-invite · product · order · payment · buttons · list · interactive · template · unknown.

MessageContext fields: identity uniqueId (16-char upper hex, per-message) · staticId (16-char upper hex, stable per room+sender — use as convo key) · channelId · chatId · receiverId · roomId · senderId · senderLid · senderName · senderDevice · timestamp · text · mentions (resolved to PN) · links. Flags: isFromMe · isGroup · isNewsletter · isBroadcast · isViewOnce · isEphemeral · isForwarded · isQuestion · isPrefix · isTagMe · isEdited · isDeleted · isPinned · isUnPinned · isBot · isSpam · isHideTags · isStatusMention · isGroupStatusMention · isGroupStatus · isStory. Methods: roomName() · receiverName() · replied() · message() · reply() · react() · citation. ctx.media variants: media attachment · poll · contact · location · event · album · group-invite · product · order · payment · link · buttons · list · interactive · template.

Domain modules (`client.*`):

• group — create/addMember/removeMember/promote/demote/updateSubject/updateDescription/leave/metadata/tagMember/inviteCode/revokeInvite/acceptInvite/toggleEphemeral/setting · + list/inviteInfo/joinRequests/approveJoin/rejectJoin/joinApproval/memberAddMode
• newsletter — create/follow/unfollow/metadata/updateName/updateDescription/updatePicture/mute/unmute/delete · + react/unreact/subscribers/messages/adminCount/changeOwner/demote/removePicture
• community — create/createGroup/linkGroup/unlinkGroup/subGroups/leave/updateSubject/updateDescription/inviteCode/revokeInvite/acceptInvite · + metadata/list/inviteInfo/toggleEphemeral/setting/memberAddMode/joinApproval
• privacy · presence
• profile — setName/setStatus/setPicture/removePicture/getPicture/getStatus
• chat — archive/unarchive/pin/unpin/mute/unmute/markRead/markUnread/star/unstar/delete/clear
• contact — check/exists/save/remove
• business (Business account) — profile/catalog/collections/orderDetails/createProduct/updateProduct/deleteProduct

Message mutations on client: pin(key,{duration?}) · unpin(key) · setDisappearing(jid, seconds) · lidToPn(lid) · pnToLid(pn) (both async).

Utils (from `'zaileys'`): JID — isJid · normalizeJid · isLidJid · isPnJid · jidToPhone · phoneToJid · jidDecode · jidEncode · jidNormalizedUser · areJidsSameUser · isJidGroup · isJidBroadcast · isJidNewsletter · isLidUser · isPnUser · getDevice. Context/media — computeUniqueId · computeStaticId · extractLinks · senderDeviceOf · epochSecondsToMs · loadMedia · detectMimeFromBuffer. Misc — chunk.

Error classes (all carry `.code`): ZaileysBuilderError, ZaileysCommandError, ZaileysDomainError, ZaileysAutomationError, ZaileysStoreError. → see references/errors.md.

When debugging zaileys

1. Is it an exception with a class/`.code`? → references/errors.md: match the code → cause → fix.
2. Is it a runtime symptom (QR keeps regenerating, reconnect loop, "module not found", ESM error)? → references/troubleshooting.md.
3. Is it "works but wrong" (no autocomplete of an option, message not sending, double-handling own messages)? → references/pitfalls.md for the anti-pattern.
4. Always verify the API exists before suggesting it — check references/api.md; never invent methods or options.

When implementing zaileys

• Start from the closest pattern in references/recipes.md.
• Apply the golden rules above.
• Prefer the typed event/context API over raw Baileys access.
• Keep examples runnable: real JIDs from env, awaited keys, single content method, rate-limited bulk.

Live docs (fetch for the latest)

These are authoritative and kept in sync with the code — fetch them when you need more detail, the newest API, or to verify before answering (do not guess when unsure):

• Docs site: <https://zeative.github.io/zaileys/>
• Full docs as one file (best for LLMs): <https://zeative.github.io/zaileys/llms-full.txt>
• Per-topic pages: /getting-started · /installation · /configuration · /client · /events · /sending-messages · /media · /interactive · /rich-responses · /commands · /automation · /storage · /error-handling · /runtimes · /troubleshooting · /api-reference (e.g. <https://zeative.github.io/zaileys/sending-messages>)