chat-adapter-baileys
WhatsApp (Baileys) adapter for the Chat SDK.
[!WARNING] This adapter uses Baileys, a third-party unofficial WhatsApp Web API. It is not an official WhatsApp/Meta API and may break when WhatsApp changes internal protocols. WhatsApp may also suspend or ban numbers/accounts that use unofficial automation. Use at your own risk and evaluate compliance requirements before production use.
...with that out of the way, let's continue with the docs.
This package lets you run Chat SDK bots on WhatsApp via Baileys. It handles the WhatsApp WebSocket connection, message parsing, formatting, media attachments, reactions, and typing indicators — so you can focus on your bot logic.
Install
Optional — for terminal QR rendering during development:
Quick Start
The setup has six steps: prepare auth, create the adapter, create a Chat instance, register handlers, initialize chat, then connect. Always register handlers before connecting — messages can arrive as soon as connect() is called.
Credentials are saved to ./auth_info on first login. Subsequent startups reuse the saved session — no QR scan needed.
Multi-Account Support
Run one adapter instance per WhatsApp account. Give each a unique adapterName to avoid thread ID collisions:
All handlers receive messages from both accounts. The thread ID prefix (baileys-main: vs baileys-sales:) tells you which account a message came from.
Adapter Config
WhatsApp Extensions
BaileysAdapter exposes extra methods for WhatsApp features that have no equivalent in the Chat SDK interface:
For multi-account setups, use createBaileysExtensions(waMain, waSales) to get a router that auto-selects the right adapter — no manual routing needed.
See Extensions for full documentation and examples.
Behavior Notes
- Transport: WebSocket-based (
connect()), not HTTP webhooks.handleWebhook()returns501. - Message history:
fetchMessages()/fetchChannelMessages()return empty arrays — WhatsApp has no REST history API. Persistmessages.upsertevents yourself if you need history. - Cards: Sent as plain-text fallback — WhatsApp has no native card format.
- Media: Incoming attachments include a lazy
fetchData()for on-demand binary download. - Reconnect: Automatic on unexpected disconnects. Does not reconnect after logout or explicit
disconnect().
Development
Docs
- Quickstart — step-by-step setup guide
- Runnable Example — full working bot with commands, media, and reactions
- Concepts Mapping — how Chat SDK concepts map to WhatsApp
- Events And Lifecycle — connection lifecycle, auth flows, reconnect behavior
- Thread IDs And Multi-Account — thread ID format and multi-account setup
- Formatting And Media — text formatting and media attachment handling
- Extensions — WhatsApp-specific features beyond the Chat SDK interface
License
MIT