Skip to main content
The Add WhatsApp skill installs WhatsApp support in NanoClaw. It handles code installation, authentication (QR or pairing code), chat registration, and verification.

​
What It Does

The Add WhatsApp skill:
  • Installs WhatsApp channel code and dependencies
  • Authenticates via QR code (browser or terminal) or pairing code
  • Registers your main chat and optional additional groups
  • Verifies the connection and provides testing instructions

​
Prerequisites

  • NanoClaw base installation complete
  • Phone with WhatsApp installed
  • For pairing code: your phone number with country code

​
How to Apply

1

Invoke the skill

Run /add-whatsapp in your NanoClaw context.
2

Choose authentication method

Select one:
  • QR code in browser (Recommended) - Large scannable QR code
  • Pairing code - Enter numeric code on your phone (no camera needed)
  • QR code in terminal - Terminal-based QR (can be small)
3

Authenticate

  • QR code: Scan with WhatsApp > Settings > Linked Devices
  • Pairing code: Enter the code in WhatsApp (expires in 60 seconds)
4

Configure chat type

Choose:
  • Shared number: Your personal WhatsApp (use self-chat or solo group)
  • Dedicated number: Separate phone/SIM for the assistant
5

Register main chat

Select where to chat:
  • Self-chat (Recommended for shared) - “Message Yourself” conversation
  • DM with bot (Recommended for dedicated) - Direct message the bot
  • Solo group - Group with just you
  • Existing group - Any WhatsApp group
6

Test the connection

Send a message in your registered chat. The assistant should respond.

​
What Changes

​
Files Created

  • src/channels/whatsapp.ts - WhatsApp channel implementation
  • store/auth/creds.json - WhatsApp authentication credentials
  • store/auth/ - Additional WhatsApp session files
  • groups/whatsapp_main/ - Main chat workspace

​
Files Modified

  • package.json - Adds @whiskeysockets/baileys, qrcode, qrcode-terminal
  • src/channels/index.ts - Imports WhatsApp channel
  • .nanoclaw/state.yaml - Records skill application
  • store/messages.db - Adds registered group entries

​
Dependencies Added

  • @whiskeysockets/baileys - WhatsApp Web API
  • qrcode - QR code generation
  • qrcode-terminal - Terminal QR code display

​
Usage

​
Main Chat (No Trigger Required)

In your main chat, any message triggers the assistant: 
You: What's the weather?
Andy: [responds immediately]

​
Additional Groups (Trigger Required)

In other groups, use the trigger word (default @Andy): 
You: @Andy what's the weather?
Andy: [responds]

You: regular message
Andy: [no response]

​
Adding More Groups

To register additional WhatsApp groups:
  1. Add the bot to the group
  2. Run /add-whatsapp again
  3. Select the group from the list
  4. Choose trigger-required mode
For shared numbers (personal WhatsApp), use self-chat or a solo group to avoid the assistant responding to all your personal messages.

​
Troubleshooting

​
QR Code Expired

QR codes expire after ~60 seconds. Re-run authentication: 
rm -rf store/auth/
npx tsx setup/index.ts --step whatsapp-auth -- --method qr-browser

​
Pairing Code Not Working

Codes expire in ~60 seconds. Ensure:
  • Phone number includes country code without + (e.g., 1234567890)
  • Phone has internet access
  • WhatsApp is updated to latest version
  • You enter the code immediately when displayed

​
”conflict” Disconnection

Two instances are using the same credentials. Stop other instances: 
pkill -f "node dist/index.js"
# Then restart
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

​
Bot Not Responding

Check:
  1. store/auth/creds.json exists
  2. Chat is registered in database
  3. Service is running
  4. Logs: tail -50 logs/nanoclaw.log

​
Group Names Not Showing

Run group metadata sync: 
npx tsx setup/index.ts --step groups

Build docs developers (and LLMs) love

Get started for freeTalk to us