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 MatClaw. 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: Verify Code

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

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

Verify the code was placed correctly:

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

Verify dependencies

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

If not installed:

npm install @whiskeysockets/baileys qrcode qrcode-terminal

Validate build

npm run build

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:

npx tsx setup/index.ts --step whatsapp-auth -- --method pairing-code --phone <their-phone-number>

(Bash timeout: 150000ms). Display PAIRING_CODE from output.

Tell the user:

A pairing code will appear. Enter it within 60 seconds — codes expire quickly.

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

If the code expires, re-run the command — a new code will be generated.

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])"

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:

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')"

DM with bot: Ask for the bot's phone number. JID = [e-mail]

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

npx tsx setup/index.ts --step groups
npx tsx setup/index.ts --step groups --list

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

Register the chat

npx tsx setup/index.ts --step register \
  --jid "<jid>" \
  --name "<chat-name>" \
  --trigger "@<trigger>" \
  --folder "whatsapp_main" \
  --channel whatsapp \
  --assistant-name "<name>" \
  --is-main \
  --no-trigger-required  # Only for main/self-chat

For additional groups (trigger-required):

npx tsx setup/index.ts --step register \
  --jid "<group-jid>" \
  --name "<group-name>" \
  --trigger "@<trigger>" \
  --folder "whatsapp_<group-name>" \
  --channel whatsapp

Phase 5: Verify

Build and restart

npm run build

Restart the service:

# macOS (launchd)
launchctl kickstart -k gui/$(id -u)/com.matclaw

# Linux (systemd)
systemctl --user restart matclaw

# Linux (nohup fallback)
bash start-matclaw.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

tail -f logs/matclaw.log

Troubleshooting

QR code expired

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

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

Pairing code not working

Codes expire in ~60 seconds. To retry:

rm -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:

rm -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 MatClaw process is running:

pkill -f "node dist/index.js"
# 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 '[e-mail]' OR jid LIKE '[e-mail]'"
3. Service is running: launchctl list | grep matclaw (macOS) or systemctl --user status matclaw (Linux)
4. Logs: tail -50 logs/matclaw.log

Group names not showing

Run group metadata sync:

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

# macOS:
launchctl unload ~/Library/LaunchAgents/com.matclaw.plist
npm run dev
# When done testing:
launchctl load ~/Library/LaunchAgents/com.matclaw.plist

# Linux:
# systemctl --user stop matclaw
# npm run dev
# systemctl --user start matclaw

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 '[e-mail]' OR jid LIKE '[e-mail]'"
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.matclaw (macOS) or npm run build && systemctl --user restart matclaw (Linux)