Setup

pnpm add @whiskeysockets/baileys

How It Works

WhatsApp doesn't have a bot API like Telegram. Instead, Baileys connects as a "linked device" to your personal WhatsApp account (like WhatsApp Web). This means:

Your agent responds as your WhatsApp number
No separate bot account needed
Works with personal and business WhatsApp

First-Time Pairing

Start the gateway — a QR code appears in the terminal
On your phone: WhatsApp → Settings → Linked Devices → Link a Device
Scan the QR code
Session is saved to disk — next restart reconnects automatically

Usage

import { whatsappChannel } from '@cogitator-ai/channels';

const whatsapp = whatsappChannel({
  sessionPath: '.cogitator/whatsapp-session',
  printQr: true,
});

Configuration

interface WhatsAppChannelConfig {
  sessionPath?: string;  // default: '.cogitator/whatsapp-session'
  qrCallback?: (qr: string) => void;
  printQr?: boolean;     // default: true
}

Features

Feature	Support
1-on-1 chats	✅
Group chats	✅
Streaming (edit)	❌ (WhatsApp doesn't support editing)
Typing indicator	✅ (presence update)
Reactions	❌
Files	✅
Markdown	✅ WhatsApp-native formatting
Auto-reconnect	✅
Session persistence	✅ (filesystem)

WhatsApp Markdown

WhatsApp uses its own formatting syntax. Cogitator auto-converts standard markdown before sending:

Standard	WhatsApp
`bold`	`bold`
`__bold__`	`bold`
`~~strike~~`	`~strike~`
Code blocks	Preserved
Inline code	Preserved

Limitations

No message editing — full response sent after generation (no streaming preview)
QR code expires after ~20 seconds, bot retries automatically
If you unlink the device from your phone, you need to re-pair
WhatsApp may temporarily ban automated accounts with high message volume

Tips

Use a dedicated phone number for production bots
The sessionPath directory must be writable
Use qrCallback to display the QR in a web UI instead of terminal

WhatsApp

On this page