/add-whatsapp

name: add-whatsapp
description: Add WhatsApp channel via native Baileys adapter. Direct connection — no Chat SDK bridge. Uses QR code or pairing code for authentication.

Add WhatsApp Channel

Adds WhatsApp support via the native Baileys adapter — a direct WhatsApp Web connection, no Chat SDK bridge. NanoClaw doesn't ship channels in trunk — this skill copies the WhatsApp adapter in from the `channels` branch.

The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Number safety check (required)

Complete this check before running any install or authentication command. If the user already said they want to use their **shared**, **personal**, **main**, **existing**, or **everyday** WhatsApp number, treat it as a shared number and show the warning immediately. Do not ask the number-type question again.

Otherwise, ask which WhatsApp number NanoClaw will use:

Which WhatsApp number will NanoClaw use? `dedicated` (recommended) — a separate number used only for NanoClaw (spare SIM, eSIM, or old phone). `shared` — your existing everyday / personal WhatsApp number.

If the answer is `shared`, show this warning — tell the user:

⚠️ Risk to your WhatsApp account

Connecting your shared or personal number could cause WhatsApp to temporarily suspend or permanently ban that number. You could lose access to the WhatsApp account, chats, and groups you rely on.

We strongly recommend using a separate, dedicated number for NanoClaw.

On your personal number, the agent lives only in your "You" / self-chat. Messages other people send you are ignored entirely — never read, never answered, never flagged for approval. Nobody else can talk to the agent.

If you want the agent reachable as its own contact, consider:
• Telegram — a bot takes ~2 minutes to set up
• a dedicated WhatsApp number — spare SIM, eSIM, or old phone
• /add-whatsapp-cloud — the official Meta Business API

Then confirm how to proceed. Do not continue with installation or authentication unless the user explicitly selects the second option:

How would you like to proceed? `dedicated` (recommended) — go back and use a dedicated number. `continue` — I understand the risk, continue with my shared number.

Remember the effective mode for the rest of this workflow: it is `shared` only when the user explicitly acknowledged the risk and continued; anyone who chose a dedicated number — up front or at the warning — continues as a dedicated-number install without seeing the warning again:

echo dedicated

echo shared

echo dedicated

Apply

1. Copy the adapter and its registration test

Fetch the `channels` branch and copy the WhatsApp adapter, its registration test, and the `whatsapp-formatting` container skill (overwrite — the branch is canonical). The `whatsapp-auth` setup step is maintained in trunk, so it is not copied here:

src/channels/whatsapp.ts
src/channels/whatsapp-registration.test.ts
container/skills/whatsapp-formatting/SKILL.md
container/skills/whatsapp-formatting/instructions.md

The `whatsapp-formatting` container skill is part of the channel payload: its `instructions.md` is inlined as a section of every group's composed project document (see `src/project-doc-compose.ts`), teaching agents WhatsApp's formatting syntax. Trunk does not ship it — without this copy step agents format WhatsApp messages with generic markdown that renders literally.

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './whatsapp.js';

3. Install the adapter packages

Pinned to exact versions — the supply-chain policy rejects ranges and `latest`. Baileys is the WhatsApp Web client; `qrcode` renders the device-link QR in the terminal; `pino` is Baileys' logger:

@whiskeysockets/baileys@7.0.0-rc14
qrcode@1.5.4
@types/qrcode@1.5.6
pino@9.6.0

4. Build and validate

Build first: it typechecks the adapter against core and proves the dependencies are installed. Then run the one integration test.

pnpm run build

pnpm exec vitest run src/channels/whatsapp-registration.test.ts

`whatsapp-registration.test.ts` imports the real channel barrel and asserts the registry contains `whatsapp`. It goes red if the `import './whatsapp.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@whiskeysockets/baileys` isn't installed (the import throws) — so it also covers the dependency from step 3. End-to-end delivery against a real WhatsApp number is verified manually once the service runs.

Authenticate

WhatsApp uses linked-device authentication — no API key, just a one-time pairing from your phone. The adapter is installed and registered, but its factory returns `null` (and the channel stays dark) until `store/auth/creds.json` exists.

The number safety check above is still required even when credentials already exist. If `store/auth/creds.json` exists, skip ahead to "Dedicated vs personal number" after completing the safety check — the link step below reports the already-linked number and moves on.

Pick how to link the device. `qr` shows a rotating QR you scan with your phone's camera; `pairing-code` shows