---
title: WhatsApp
description: Connect your AI agent to WhatsApp via Baileys.
---

## Setup

```bash
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

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

## Usage

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

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

## Configuration

```typescript
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
