whatsapp-bot-builder

Usage

Loaded automatically when its description matches the active task. The body below provides the working context.

Use this skill when

Building WhatsApp bots or automation
Integrating WhatsApp messaging into applications
Working with Baileys, whatsapp-web.js, or venom-bot
Implementing WhatsApp Business API integration

Do not use this skill when

Building Telegram bots (use telegram-bot-builder)
Working with official WhatsApp Cloud API only (basic REST)
The task is unrelated to WhatsApp messaging

Purpose

Expert in WhatsApp bot development using unofficial libraries (Baileys, whatsapp-web.js) and official Business API. Deep knowledge of session management, multi-device protocol, rate limiting, and media handling.

Capabilities

Core Libraries

Baileys (@whiskeysockets/baileys) — lightweight, multi-device, recommended
whatsapp-web.js — Puppeteer-based, heavier but mature
venom-bot — alternative Puppeteer-based client
Official WhatsApp Business API via Meta — paid, reliable, production-grade

Message Handling

Text messages, media (images, video, audio, documents)
Buttons, lists, and interactive message templates
Message reactions and replies
Group message handling and admin operations
Contact and location messages

Session & Authentication

Multi-file auth state persistence (prevent re-QR on restart)
Multi-device protocol support (phone doesn't need to stay online)
Session backup and restoration across restarts
QR code generation for initial pairing

Rate Limiting & Safety

WhatsApp bans numbers sending >200 msgs/day to new contacts
Warm-up period required for new numbers
Different limits for groups vs individual chats
Official Business API has higher limits with verified numbers

Behavioral Traits

Always persists auth state to prevent re-QR-scan on restart
Uses Baileys multi-device protocol (not legacy)
Implements graceful shutdown to save session state
Respects rate limits — queues messages with delays
Handles connection drops with automatic reconnection
Validates phone number format (1234567890@s.whatsapp.net)
Uses downloadMediaMessage() for received media

Important Constraints

Unofficial libraries may break when WhatsApp updates protocol
Rate limits are strict — WhatsApp will ban numbers that spam
Media size limits — 16MB for images, 64MB for video/documents
Business API — for production at scale, use official Meta API (paid)
Groups — bot must be admin for management operations
Number format — always use {number}@s.whatsapp.net format
Multi-device — Baileys supports natively, phone can go offline