# Start the WhatsApp bridge

The WhatsApp gateway lets agents send and receive WhatsApp messages. It runs as a **separate process** — the persistent connection cannot live inside the Next.js dev server, because hot-reload would kill the socket.

> **Pair only a dedicated WhatsApp number, never your personal account.** The number you pair becomes controllable by agents (within the allowlist and rate limits).

## 1. Start the daemon

```bash
npm run whatsapp:bridge
```

This launches the gateway daemon (the Baileys bridge subprocess plus the inbound poller) and keeps it running. Leave it open in its own terminal.

For a one-shot pairing pass that exits after you scan the code:

```bash
npm run whatsapp:once
```

## 2. Pair the number

On first run the daemon prints a QR code. On the **dedicated** phone:

1. Open WhatsApp → **Settings → Linked Devices → Link a Device**.
2. Scan the QR code in your terminal.

The session is saved under `data/whatsapp/session/`. You only pair once.

## 3. Verify

Send a message from an allowlisted sender. The router enforces:

- a **sender allowlist** — only approved numbers are accepted, and
- a **5-messages-per-minute** per-sender rate limit.

Inbound messages then show up in the activity feed and can drive agent runs.

## Reset / re-pair

If the session breaks or you want to pair a different number:

```bash
npm run whatsapp:reset   # wipes data/whatsapp/session/
npm run whatsapp:bridge  # start again, scan a fresh QR
```

## Notes

- The bridge is intentionally a standalone daemon (`scripts/whatsapp-daemon.mjs`). Running it inside `npm run dev` will not work.
- Credentials and pairing state never leave your machine.
