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 (no Chat SDK bridge).

Install

NanoClaw doesn't ship channels in trunk. This skill copies the native WhatsApp (Baileys) adapter and its whatsapp-auth setup step in from the channels branch. No Chat SDK bridge.

Pre-flight (idempotent)

Skip to Credentials if all of these are already in place:

• src/channels/whatsapp.ts exists
• src/channels/whatsapp-registration.test.ts exists
• src/channels/whatsapp.test.ts exists
• src/channels/index.ts contains import './whatsapp.js';
• setup/whatsapp-auth.ts and setup/groups.ts both exist
• container/skills/whatsapp-formatting/instructions.md exists
• setup/index.ts's STEPS map contains both 'whatsapp-auth': and groups:
• @whiskeysockets/baileys, qrcode, pino are listed in package.json dependencies
• .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts exists (ships with this skill)

Otherwise continue. Every step below is safe to re-run.

1. Fetch the channels branch

git fetch origin channels

2. Copy the adapter and setup steps

git show origin/channels:src/channels/whatsapp.ts                      > src/channels/whatsapp.ts
git show origin/channels:src/channels/whatsapp-registration.test.ts    > src/channels/whatsapp-registration.test.ts
git show origin/channels:src/channels/whatsapp.test.ts                 > src/channels/whatsapp.test.ts
git show origin/channels:setup/whatsapp-auth.ts                        > setup/whatsapp-auth.ts
git show origin/channels:setup/groups.ts                               > setup/groups.ts
mkdir -p container/skills/whatsapp-formatting
git show origin/channels:container/skills/whatsapp-formatting/SKILL.md        > container/skills/whatsapp-formatting/SKILL.md
git show origin/channels:container/skills/whatsapp-formatting/instructions.md > container/skills/whatsapp-formatting/instructions.md

The whatsapp-formatting container skill is part of the channel payload: its instructions.md becomes the skill-whatsapp-formatting.md fragment in every group's composed CLAUDE.md (see src/claude-md-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.

3. Append the self-registration import

Append to src/channels/index.ts (skip if already present):

import './whatsapp.js';

4. Register the setup steps

In setup/index.ts, add these entries to the STEPS map (skip lines already present):

groups: () => import('./groups.js'),
'whatsapp-auth': () => import('./whatsapp-auth.js'),

5. Install the adapter packages (pinned)

pnpm install @whiskeysockets/baileys@7.0.0-rc.9 qrcode@1.5.4 @types/qrcode@1.5.6 pino@9.6.0

6. Build and validate

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

Both must be clean before proceeding. whatsapp-registration.test.ts is the one integration test: it 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 (so the channel genuinely would not register), or if @whiskeysockets/baileys isn't installed (the import throws) — so it also implicitly verifies the dependency from step 5.

End-to-end message delivery against a real WhatsApp number is verified manually once the service is running — see Credentials, Wiring, and Troubleshooting.

Credentials

WhatsApp uses linked-device authentication — no API key, just a one-time pairing from your phone.

Check current state

Check if WhatsApp is already authenticated. If store/auth/creds.json exists, skip to "Dedicated vs personal number".

test -f store/auth/creds.json && echo "WhatsApp auth exists" || echo "No WhatsApp auth"

Detect environment

Check whether the environment is headless (no display server):

[[ -z "$DISPLAY" && -z "$WAYLAND_DISPLAY" && "$OSTYPE" != darwin* ]] && echo "IS_HEADLESS=true" || echo "IS_HEADLESS=false"

Ask the user

Use AskUserQuestion to collect configuration. Adapt auth options based on environment:

If IS_HEADLESS=true AND not WSL → AskUserQuestion: How do you want to authenticate WhatsApp?

• Pairing code (Recommended) - Enter a numeric code on your phone (no camera needed, requires phone number)
• QR code in terminal - Displays QR code in the terminal (can be too small on some displays)

Otherwise (macOS, desktop Linux, or WSL) → AskUserQuestion: How do you want to authenticate WhatsApp?

• QR code in browser (Recommended) - Runs a small local HTTP server that renders the rotating QR as a PNG and auto-opens your default browser
• Pairing code - Enter a numeric code on your phone (no camera needed, requires phone number)
• QR code in terminal - Displays QR code in the terminal (can be too small on some displays)

If they chose pairing code:

AskUserQuestion: What is your phone number? (Digits only — country code followed by your 10-digit number, no + prefix, spaces, or dashes. Example: 14155551234 where 1 is the US country code and 4155551234 is the phone number.)

Clean previous auth state (if re-authenticating)

rm -rf store/auth/

Run WhatsApp authentication

For QR code in browser (recommended):

pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts

(Bash timeout: 150000ms)

The wrapper spawns setup/index.ts --step whatsapp-auth -- --method qr, parses each rotating QR from its WHATSAPP_AUTH_QR status blocks, and serves the current QR as a PNG on a local HTTP server (default port 8765, falls back to a free port). Flags: --clean (wipes store/auth/ before spawning) and --port N.

Tell the user:

A browser window will open with a QR code.

1. Open WhatsApp > Settings > Linked Devices > Link a Device
2. Scan the QR code in the browser
3. The page will show "Authenticated!" when done

For QR code in terminal:

pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method qr

(Bash timeout: 150000ms)

The setup driver emits each rotating QR as a WHATSAPP_AUTH_QR status block; when run directly (not through setup:auto) the raw QR string is printed and your terminal must render it as ASCII. If your terminal can't render it readably, use the browser method above.

Tell the user:

1. Open WhatsApp > Settings > Linked Devices > Link a Device
2. Scan the QR code displayed in the terminal

For pairing code:

Tell the user to have WhatsApp open on Settings > Linked Devices > Link a Device, ready to tap "Link with phone number instead" — the code expires in ~60 seconds and must be entered immediately.

Run the auth process in the background and poll store/pairing-code.txt for the code:

rm -f store/pairing-code.txt && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number> > /tmp/wa-auth.log 2>&1 &

Then immediately poll for the code (do NOT wait for the background command to finish):

for i in $(seq 1 20); do [ -f store/pairing-code.txt ] && cat store/pairing-code.txt && break; sleep 1; done

Display the code to the user the moment it appears. Tell them:

Enter this code now — it expires in ~60 seconds.

1. Open WhatsApp > Settings > Linked Devices > Link a Device
2. Tap Link with phone number instead
3. Enter the code immediately

After the user enters the code, poll for authentication to complete:

for i in $(seq 1 60); do grep -q 'STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done

If failed: logged_out → delete store/auth/ and re-run. timeout → ask user, offer retry.

Verify authentication succeeded

test -f store/auth/creds.json && echo "Authentication successful" || echo "Authentication failed"

Dedicated vs personal number

The adapter behaves fundamentally differently depending on whether the linked number is the assistant's own or the operator's personal one. The switch is ASSISTANT_HAS_OWN_NUMBER in .env, read by the adapter itself at startup. Inference rule: absent (or anything other than true) means shared/personal — the safe default, since misreading a personal number as dedicated makes the bot claim messages addressed to the human.

• Shared/personal number (ASSISTANT_HAS_OWN_NUMBER unset or not true) — DMs to this number and group @-tags of it address the human, not the bot. The adapter never emits a mention signal (mentions: 'never' in its declared channel defaults), so: no stranger DM ever auto-creates a messaging group or raises an admin approval card; group wirings default to a name pattern (\b<AgentName>\b) instead of platform mentions; auto-created chats default to unknown_sender_policy: 'strict'; outbound messages are prefixed with the assistant's name.
• Dedicated number (ASSISTANT_HAS_OWN_NUMBER=true) — everything sent to the number is for the bot. DMs and group mentions carry a real mention signal (mentions: 'platform'), unknown senders escalate via request_approval approval cards, and card-approved groups wire with engage_mode: 'mention'. No name prefix on outbound.

AskUserQuestion: Is this a shared phone number (personal WhatsApp) or a dedicated number?

• Shared number — your personal WhatsApp (bot prefixes messages with its name)
• Dedicated number — a separate phone/SIM for the assistant

Write the answer to .env explicitly in both cases (don't rely on the inference rule for new installs):

# Dedicated:
ASSISTANT_HAS_OWN_NUMBER=true
# Shared/personal:
ASSISTANT_HAS_OWN_NUMBER=false

Update path: existing install, flag unset

If WhatsApp auth already exists (store/auth/creds.json present) but .env has no ASSISTANT_HAS_OWN_NUMBER line, the install predates the explicit switch. Ask the operator which mode applies and write it explicitly.

Suggest a default by comparing the authed number against the wired DM chat:

# The number this install is authenticated as
node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0])"
# The wired WhatsApp DM chats
pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id=mga.messaging_group_id WHERE mg.channel_type='whatsapp' AND mg.is_group=0"

If the wired DM's phone equals the authed number, the operator is talking to the bot in their own self-chat — that's a personal number: suggest Shared. If they differ, the operator messages the bot from a different number: suggest Dedicated. Confirm with the operator either way, then write the flag and restart the service.

Migration audit: spam-era group wirings

Before the shared-number fix, group chats approved via the channel-registration card were wired engage_mode='pattern' with pattern . — respond-to-everything — because the card flow couldn't tell groups from DMs on non-threaded platforms. On a personal number this shows up as the bot answering every message in family/work groups after someone once tapped Connect on a spam-triggered card.

List the suspect wirings (host service running — ncl is socket-only):

ncl wirings list --engage-mode pattern --engage-pattern "." --json

Cross-reference against WhatsApp group chats (ncl messaging-groups list --channel-type whatsapp --is-group 1). For each wiring with pattern . on a WhatsApp group that is not the operator's deliberate always-on chat (e.g. their self-chat), offer:

• Flip to name-based engagement: ncl wirings update <wiring-id> --engage-mode pattern --engage-pattern '\b<AgentName>\b' (or --engage-mode mention on a dedicated number)
• Delete the wiring: ncl wirings delete <wiring-id>

Stale approval cards from that era can also linger. Clear pending channel approvals for chats the operator doesn't want wired:

pnpm exec tsx scripts/q.ts data/v2.db "DELETE FROM pending_channel_approvals WHERE messaging_group_id IN (SELECT id FROM messaging_groups WHERE channel_type='whatsapp')"

Next Steps

If you're in the middle of /setup, return to the setup flow now.

Otherwise, run /manage-channels to wire this channel to an agent group.

Channel Info

• type: whatsapp
• terminology: WhatsApp calls them "groups" and "chats." A "chat" is a 1:1 DM; a "group" has multiple members.
• how-to-find-id: DMs use <phone>@s.whatsapp.net (e.g. [e-mail]). Groups use <id>@g.us. To find your number: node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')". Groups are auto-discovered — check pnpm exec tsx scripts/q.ts data/v2.db "SELECT platform_id, name FROM messaging_groups WHERE channel_type='whatsapp' AND is_group=1".
• supports-threads: no
• typical-use: Interactive chat — direct messages or small groups
• default-isolation: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.

Features

• Markdown formatting — **bold**→*bold*, *italic*→_italic_, headings→bold, code blocks preserved
• Approval questions — ask_user_question renders with /approve, /reject slash commands
• File attachments — send and receive images, video, audio, documents
• Reactions — send emoji reactions on messages
• Typing indicators — composing presence updates
• Credential requests — text fallback (WhatsApp has no modal support)

Not supported (WhatsApp linked device limitation): edit messages, delete messages.

Troubleshooting

QR code expired

QR codes expire after ~60 seconds. The browser wrapper rotates automatically as long as it's running; if it was stopped, re-run with --clean:

pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean

Pairing code not working

Codes expire in ~60 seconds. Delete auth and retry:

rm -rf store/auth/ && pnpm exec tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <phone>

Ensure: digits only (no +), phone has internet, WhatsApp is updated.

WhatsApp's pairing-code flow occasionally rejects valid codes with "Couldn't link device — An error happened. Please try again." This is a server-side rejection unrelated to the code itself; we've seen it happen twice in a row on fresh dedicated numbers. If you hit it more than once, switch to QR-browser auth — it has a noticeably higher success rate:

pnpm exec tsx .claude/skills/add-whatsapp/scripts/wa-qr-browser.ts --clean

"waiting for this message" on reactions

Signal sessions corrupted from rapid restarts. Clear sessions.

Run from your NanoClaw project root:

source setup/lib/install-slug.sh
systemctl --user stop $(systemd_unit)
rm store/auth/session-*.json
systemctl --user start $(systemd_unit)

Bot not responding

1. Auth exists: test -f store/auth/creds.json
2. Connected: grep "Connected to WhatsApp" logs/nanoclaw.log | tail -1
3. Channel wired: pnpm exec tsx scripts/q.ts data/v2.db "SELECT mg.platform_id, mg.name FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id=mga.messaging_group_id WHERE mg.channel_type='whatsapp'"
4. Service running: systemctl --user status "$(. setup/lib/install-slug.sh && systemd_unit)"

"conflict" disconnection

Two instances connected with same credentials. Ensure only one NanoClaw process is running.

Trunk updated but shared-number behavior unchanged (stale adapter copy)

The shared-number behavior (no stranger approval cards, name-pattern group defaults) lives in the adapter copy at src/channels/whatsapp.ts, installed from the channels branch — not in trunk. If you updated trunk via /update-nanoclaw but skipped the skill-update step, the old adapter copy neither reads ASSISTANT_HAS_OWN_NUMBER itself nor declares channel defaults, so trunk falls back to the legacy behavior: approval cards still fire on a personal number, and new wirings get the channel-blind defaults. Symptoms of the skew:

• .env says ASSISTANT_HAS_OWN_NUMBER=false (or unset) but strangers' DMs still raise approval cards
• ncl wirings create on a WhatsApp group defaults to mention instead of a name pattern

Fix: re-run /add-whatsapp (or /update-skills) to pull the current adapter from the channels branch, then restart the service. The reverse skew (new adapter, old trunk) can't happen — the adapter's defaults field is optional and old trunk ignores it.