# WhatsApp channel

A linked WhatsApp number via [Baileys](https://github.com/WhiskeySockets/Baileys)
(multi-device). Unlike the other channels there's no webhook — Callbackfy holds a live
socket to WhatsApp, so the credentials come from **pairing**, not a config field.

## Configuration

Channels → **New channel** → Kind = **whatsapp**.

| Field                       | What it is                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| **Default agent**           | Answers DMs and any allowed group not mapped to a specific agent.                          |
| **Identity**                | A label for the number you'll link, e.g. `+34 600 …`. The real binding happens at pairing. |
| **WhatsApp rules**          | DMs / groups behavior (below).                                                             |
| **Command routes / Guards** | Optional — see the [common docs](./README.md).                                             |

Leave credentials empty — auth is handled by the pairing flow.

## Pairing

Save the channel, then open it and use the **WhatsApp** panel:

1. **Connect** → choose **QR** (scan from WhatsApp → Linked devices) or **pairing code** (enter the international number, then type the 8-char code in WhatsApp).
2. Once status shows **connected**, the number is linked. The session persists in the database and reconnects on restart.
3. **Groups** lists the groups the number belongs to, so you can pick which to allow.

## Reply rules

- **`allowDirectMessages`** — answer one-to-one DMs.
- **Groups are deny-by-default** — a group is answered only if it's in **`allowedGroups`** or mapped in **`groupAgents`**.
- **`groupRequireMention`** — in groups, only reply when the linked number is `@`-mentioned.
- **Per-group agents** (`groupAgents`) — one number can answer different topics in different groups.

Commands: on WhatsApp the slash is optional (`stocks` or `/stocks`); the slash form also skips the mention requirement in groups.

## Operational notes

- **One connection per number.** WhatsApp allows a single active session, so only **one** Callbackfy instance may hold it. Run extra instances with `WHATSAPP_ENABLED=false`. If two instances share the credentials you'll see a reconnect loop (`code 440` = connection replaced).
- Set `WHATSAPP_ENABLED=false` on dev boxes so they never fight the deployed bot over the same number.