Introduction

chat-adapter-baileys is the WhatsApp (Baileys) adapter for the Chat SDK.

...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.

Why use it?

• Write once, run anywhere: your bot logic targets the platform-agnostic Chat SDK, so the same handlers work across every adapter. Add or swap platforms without rewriting.
• No official API required: connect an ordinary WhatsApp account via QR or pairing code. No Meta Cloud API approval, business verification, or per-message fees.
• Batteries included: the adapter manages the WebSocket connection, message parsing, formatting, media up/download, reactions, and typing indicators for you.
• Multi-account ready: run several WhatsApp numbers from one bot, each isolated by a thread-ID prefix.
• WhatsApp-native extras: quoted replies, read receipts, presence, location pins, polls, and group-participant lookups beyond the base Chat SDK interface.
• Resilient sessions: credentials persist after first login (no re-scan), and the connection auto-reconnects on unexpected drops.

Beyond the official API

Because it talks to WhatsApp Web directly, the adapter exposes capabilities that the official WhatsApp Cloud API restricts or doesn't offer:

• Free-form messaging: message any chat without the 24-hour customer-service window or pre-approved message templates.
• Reactions: add, remove, and observe emoji reactions.
• Read receipts: send blue double-ticks on demand with markRead(...).
• Presence control: set the bot's global online/offline status and show typing indicators.
• Polls: create native WhatsApp polls with sendPoll(...).
• Location pins: send native location messages with sendLocation(...).
• Group insights: list group participants and their admin roles with fetchGroupParticipants(...).
• Quoted replies: reply with the native WhatsApp reply bubble via reply(...).

See Extensions for the full list and usage examples.

Support Overview

Chat SDK Base

Baileys Extras

Getting Started

New to the adapter? Start here:

Core Topics

Connection and Lifecycle

Thread Management

Messages and Media

Error Handling

Migration

Quick Reference

Package exports:

import {
  createBaileysAdapter,   // Factory function
  BaileysAdapter,         // Class (for type annotations)
  BaileysFormatConverter, // Text format converter
  isBaileysAdapter,       // Type guard
  requireBaileysAdapter,  // Type assertion
} from "chat-adapter-baileys";
import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { useMultiFileAuthState } from "baileys";

QR code authentication (most common):

const { state, saveCreds } = await useMultiFileAuthState("./auth_info");

const whatsapp = createBaileysAdapter({
  auth: { state, saveCreds },
  userName: "my-bot",
  onQR: async (qr) => {
    const QRCode = await import("qrcode");
    console.log(await QRCode.toString(qr, { type: "terminal" }));
  },
});

const bot = new Chat({
  userName: "my-bot",
  adapters: { whatsapp },
  state: createMemoryState(),
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello!");
  await thread.subscribe();
});

await bot.initialize();
await whatsapp.connect();

Pairing code authentication (alternative):

const whatsapp = createBaileysAdapter({
  auth: { state, saveCreds },
  userName: "my-bot",
  phoneNumber: "12345678901",  // E.164 format, no "+"
  onPairingCode: (code) => {
    console.log("Enter this code in WhatsApp → Linked Devices:", code);
  },
});

Accessing WhatsApp-specific methods:

import { requireBaileysAdapter } from "chat-adapter-baileys";

bot.onSubscribedMessage(async (thread, message) => {
  const wa = requireBaileysAdapter(thread);
  await wa.reply(message, "Got it!");
  await wa.markRead({
    threadId: thread.id,
    messageIds: [message.id],
  });
});

Need Help?

Package Info

• npm: chat-adapter-baileys
• Repository: Part of the Chat SDK ecosystem
• Baileys version: >=7.0.0-rc13 <8