/add-whatsapp

name: add-whatsapp
description: Add WhatsApp as a channel. Can replace other channels entirely or run alongside them. Uses QR code or pairing code for authentication.

Add WhatsApp Channel

This skill adds WhatsApp support to ClaudeClaw. It installs the WhatsApp channel code, dependencies, and guides through authentication, registration, and configuration.

Phase 1: Pre-flight

Check current state

Check if WhatsApp is already configured. If `store/auth/` exists with credential files, skip to Phase 4 (Registration) or Phase 5 (Verify).

ls store/auth/creds.json 2>/dev/null && 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) - Opens a browser window with a large, scannable QR code
• **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? (Include country code without +, e.g., 1234567890)

Phase 2: Apply Code Changes

Check if `src/channels/whatsapp.ts` already exists. If it does, skip to Phase 3 (Authentication).

Ensure channel remote

git remote -v

If `whatsapp` is missing, add it:

git remote add whatsapp https://github.com/qwibitai/claudeclaw-whatsapp.git

Merge the skill branch

git fetch whatsapp main
git merge whatsapp/main || {
  git checkout --theirs package-lock.json
  git add package-lock.json
  git merge --continue
}

This merges in:

• `src/channels/whatsapp.ts` (WhatsAppChannel class with self-registration via `registerChannel`)
• `src/channels/whatsapp.test.ts` (41 unit tests)
• `src/channels/whatsapp-auth.ts` (standalone WhatsApp authentication script)
• `setup/whatsapp-auth.ts` (WhatsApp auth setup step)
• `import './whatsapp.js'` appended to the channel barrel file `src/channels/index.ts`
• `'whatsapp-auth'` step added to `setup/index.ts`
• `@whiskeysockets/baileys`, `qrcode`, `qrcode-terminal` npm dependencies in `package.json`
• `ASSISTANT_HAS_OWN_NUMBER` in `.env.example`

If the merge reports conflicts, resolve them by reading the conflicted files and understanding the intent of both sides.

Validate code changes

npm install
npm run build
npx vitest run src/channels/whatsapp.test.ts

All tests must pass and build must be clean before proceeding.

Phase 3: Authentication

Clean previous auth state (if re-authenticating)

rm -rf store/auth/

Run WhatsApp authentication

For QR code in browser (recommended):

npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser

(Bash timeout: 150000ms)

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:

npx tsx setup/index.ts --step whatsapp-auth -- --method qr-terminal

Tell the user to run `npm run auth` in another terminal, then:

> 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 && npx 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 'AUTH_STATUS: authenticated' /tmp/wa-auth.log 2>/dev/null && echo "authenticated" && break; grep -q 'AUTH_STATUS: failed' /tmp/wa-auth.log 2>/dev/null && echo "failed" && break; sleep 2; done

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

Verify authentication succeeded

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

Configure environment

Channels auto-enable when their credentials are present — WhatsApp activates when `store/auth/creds.json` exists.

Sync to container environment:

mkdir -p data/env && cp .env data/env/env

Phase 4: Registration

Configure trigger and channel type

Get the bot's WhatsApp number: `node -e "const c=require('./store/auth/creds.json');console.log(c.me.id.split(':')[0].split('@')[0])"`

AskUserQue