Add WhatsApp Channel

This skill adds WhatsApp support to NanoClaw. 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).

bash
1ls 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):

bash
1[[ -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: Verify Code

Apply the skill to install the WhatsApp channel code and dependencies:

bash
1npx tsx scripts/apply-skill.ts .claude/skills/add-whatsapp

Verify the code was placed correctly:

bash
1test -f src/channels/whatsapp.ts && echo "WhatsApp channel code present" || echo "ERROR: WhatsApp channel code missing — re-run skill apply"

Verify dependencies

bash
1node -e "require('@whiskeysockets/baileys')" 2>/dev/null && echo "Baileys installed" || echo "Installing Baileys..."

If not installed:

bash
1npm install @whiskeysockets/baileys qrcode qrcode-terminal

Validate build

bash
1npm run build

Build must be clean before proceeding.

Phase 3: Authentication

Clean previous auth state (if re-authenticating)

bash
1rm -rf store/auth/

Run WhatsApp authentication

For QR code in browser (recommended):

bash
1npx 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:

bash
1npx 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:

bash
1rm -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):

bash
1for 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:

bash
1for 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

bash
1test -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:

bash
1mkdir -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])"

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

• Shared number - Your personal WhatsApp number (recommended: use self-chat or a solo group)
• Dedicated number - A separate phone/SIM for the assistant

AskUserQuestion: What trigger word should activate the assistant?

• @Andy - Default trigger
• @Claw - Short and easy
• @Claude - Match the AI name

AskUserQuestion: What should the assistant call itself?

• Andy - Default name
• Claw - Short and easy
• Claude - Match the AI name

AskUserQuestion: Where do you want to chat with the assistant?

Shared number options:

• Self-chat (Recommended) - Chat in your own "Message Yourself" conversation
• Solo group - A group with just you and the linked device
• Existing group - An existing WhatsApp group

Dedicated number options:

• DM with bot (Recommended) - Direct message the bot's number
• Solo group - A group with just you and the bot
• Existing group - An existing WhatsApp group

Get the JID

Self-chat: JID = your phone number with @s.whatsapp.net. Extract from auth credentials:

bash
1node -e "const c=JSON.parse(require('fs').readFileSync('store/auth/creds.json','utf-8'));console.log(c.me?.id?.split(':')[0]+'@s.whatsapp.net')"

DM with bot: The JID is the user's phone number — the number they will message from (not the bot's own number). Ask:

AskUserQuestion: What is your personal phone number? (The number you'll use to message the bot — include country code without +, e.g. 1234567890)

JID = <user-number>@s.whatsapp.net

Group (solo, existing): Run group sync and list available groups:

bash
1npx tsx setup/index.ts --step groups
2npx tsx setup/index.ts --step groups --list

The output shows JID|GroupName pairs. Present candidates as AskUserQuestion (names only, not JIDs).

Register the chat

bash
1npx tsx setup/index.ts --step register \
2  --jid "<jid>" \
3  --name "<chat-name>" \
4  --trigger "@<trigger>" \
5  --folder "whatsapp_main" \
6  --channel whatsapp \
7  --assistant-name "<name>" \
8  --is-main \
9  --no-trigger-required  # For self-chat and DM with bot (1:1 conversations don't need a trigger prefix)

For additional groups (trigger-required):

bash
1npx tsx setup/index.ts --step register \
2  --jid "<group-jid>" \
3  --name "<group-name>" \
4  --trigger "@<trigger>" \
5  --folder "whatsapp_<group-name>" \
6  --channel whatsapp

Phase 5: Verify

Build and restart

bash
1npm run build

Restart the service:

bash
1# macOS (launchd)
2launchctl kickstart -k gui/$(id -u)/com.nanoclaw
3
4# Linux (systemd)
5systemctl --user restart nanoclaw
6
7# Linux (nohup fallback)
8bash start-nanoclaw.sh

Test the connection

Tell the user:

Send a message to your registered WhatsApp chat:

• For self-chat / main: Any message works
• For groups: Use the trigger word (e.g., "@Andy hello")

The assistant should respond within a few seconds.

Check logs if needed

bash
1tail -f logs/nanoclaw.log

Troubleshooting

QR code expired

QR codes expire after ~60 seconds. Re-run the auth command:

bash
1rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts

Pairing code not working

Codes expire in ~60 seconds. To retry:

bash
1rm -rf store/auth/ && npx tsx src/whatsapp-auth.ts --pairing-code --phone <phone>

Enter the code immediately when it appears. Also ensure:

1. Phone number includes country code without + (e.g., 1234567890)
2. Phone has internet access
3. WhatsApp is updated to the latest version

If pairing code keeps failing, switch to QR-browser auth instead:

bash
1rm -rf store/auth/ && npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser

"conflict" disconnection

This happens when two instances connect with the same credentials. Ensure only one NanoClaw process is running:

bash
1pkill -f "node dist/index.js"
2# Then restart

Bot not responding

Check:

1. Auth credentials exist: ls store/auth/creds.json
2. Chat is registered: sqlite3 store/messages.db "SELECT * FROM registered_groups WHERE jid LIKE '%whatsapp%' OR jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"
3. Service is running: launchctl list | grep nanoclaw (macOS) or systemctl --user status nanoclaw (Linux)
4. Logs: tail -50 logs/nanoclaw.log

Group names not showing

Run group metadata sync:

bash
1npx tsx setup/index.ts --step groups

This fetches all group names from WhatsApp. Runs automatically every 24 hours.

After Setup

If running npm run dev while the service is active:

bash
1# macOS:
2launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist
3npm run dev
4# When done testing:
5launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist
6
7# Linux:
8# systemctl --user stop nanoclaw
9# npm run dev
10# systemctl --user start nanoclaw

Removal

To remove WhatsApp integration:

1. Delete auth credentials: rm -rf store/auth/
2. Remove WhatsApp registrations: sqlite3 store/messages.db "DELETE FROM registered_groups WHERE jid LIKE '%@g.us' OR jid LIKE '%@s.whatsapp.net'"
3. Sync env: mkdir -p data/env && cp .env data/env/env
4. Rebuild and restart: npm run build && launchctl kickstart -k gui/$(id -u)/com.nanoclaw (macOS) or npm run build && systemctl --user restart nanoclaw (Linux)