---
name: connect-whatsapp
description: Guide the user through connecting WhatsApp via QR code pairing, registering admin phones, and selecting the public agent. Complete setup — not just pairing.
---

# Connect WhatsApp

Conversational flow for linking a WhatsApp account to {{productName}} via Baileys QR pairing, followed by admin phone registration and public agent selection. All three phases are required for a correctly configured WhatsApp channel.

## When to activate

User says anything about connecting, linking, setting up, or adding WhatsApp.

## Prerequisites

Call `whatsapp-status` first to check the current state. If already connected, tell the user and offer to relink. If connected but admin phones or public agent are not configured, proceed to the relevant post-pairing step.

## Flow

### Phase 1: QR Pairing

1. **Initiate pairing** — call `whatsapp-login-start`. If the account is already linked and the user didn't say "relink", inform them and skip to Phase 2.

2. **QR code renders automatically** — the tool delivers the QR image to the chat surface inline. Tell the user: "Open WhatsApp on your phone → Settings → Linked Devices → Link a Device → Scan this QR code."

3. **Wait for scan** — call `whatsapp-login-wait`. This polls for up to 60 seconds. While waiting, tell the user you're watching for the scan.

4. **Confirm connection** — when pairing completes, the tool returns the linked phone number (the *self phone* — the WhatsApp account {{productName}} now controls). The platform automatically registers this phone as an admin phone and creates the WhatsApp config in `account.json`. Confirm: "WhatsApp connected as {phone}. Your phone is registered as admin."

5. **Verify** — call `whatsapp-status` to confirm the connection is live.

### Phase 2: Additional Admin Phones

The self phone from Phase 1 is automatically registered as an admin phone. If the user has additional phones that should also have admin access (e.g. a partner, co-owner, or second device), register them here.

1. **Offer additional admin phones** — "Would you like to add any other phone numbers as admin? For example, a partner or co-owner who should also have admin access."

2. **Register additional phones** — For each phone the user provides, call `whatsapp-config` with `action: "add-admin-phone"` and `phone: "{E.164 number}"`. The tool validates the format and adds it to the admin list.

3. **Confirm** — "Added {number} as admin. Messages from this number will route to the admin agent." Use `whatsapp-config` with `action: "list-admin-phones"` to show the complete list.

4. **Skip if not needed** — If the user declines, proceed to Phase 3. The self phone is already registered.

### Phase 3: Public Agent Selection

WhatsApp inbound from non-admin phones routes to a public agent configured in the WhatsApp config — not the account-level `defaultAgent`. The user must explicitly choose which agent handles WhatsApp. There is no automatic fallback; if no public agent is set, WhatsApp silently rejects non-admin messages.

1. **Check current state** — Call `whatsapp-config` with `action: "get-public-agent"` to see if one is already set. Also call `account-manage` to list the available public agents.

2. **Ask which agent should handle WhatsApp** — "Which of your public agents should respond to WhatsApp messages from customers?"

3. **Set the public agent** — Call `whatsapp-config` with `action: "set-public-agent"` and `slug: "{chosen-slug}"`.

4. **Open the DM policy** — Call `whatsapp-config` with `action: "update-config"`, `dmPolicy: "open"`, and `allowFrom: ["*"]`. Without this, all non-admin messages are silently dropped regardless of which public agent is configured.

5. **Confirm** — "WhatsApp messages from customers will be handled by {agent name}."

If only one public agent exists, confirm it as the choice rather than asking. If no public agents exist, tell the user: "You don't have a public agent yet. WhatsApp will be connected but won't respond to customer messages until you create one and set it with `whatsapp-config action: set-public-agent`."

## Relinking

If the user says "relink WhatsApp" or the status shows disconnected with a 401 error:
1. Call `whatsapp-login-start` with `force: true` to clear old credentials and generate a fresh QR
2. Follow the same flow from Phase 1

Admin phone registration and public agent selection persist across relinks — no need to repeat Phases 2-3 unless the user wants to change them.

## Troubleshooting

- **QR expired** — generate a new one with `whatsapp-login-start`
- **Phone not scanning** — ensure the phone has internet, WhatsApp is updated, and the user is in Linked Devices
- **Keeps disconnecting** — check `whatsapp-status` for error details. A 401 means re-link is needed. Repeated transient errors suggest network issues on the device.
- **Messages routing as public** — the user's personal phone is not in `adminPhones`. Call `whatsapp-config` with `action: "add-admin-phone"` and the user's phone number to register it.

## Language

Use plain English:
- "QR code" not "Baileys pairing token"
- "Link your phone" not "initiate WebSocket connection"
- "WhatsApp is connected" not "Baileys socket is open"
- "admin phone" not "allowFrom entry"
- "public agent" not "defaultAgent slug"
