/add-whatsapp skill. It uses the Baileys library and merges the skill/whatsapp branch into your fork.
Overview
NanoClaw connects to WhatsApp using the Baileys library, which provides a clean interface to WhatsApp’s Web API.Features
- Group and individual chats - Message the assistant in any WhatsApp chat
- Multi-device support - Uses WhatsApp’s official multi-device protocol
- Automatic reconnection - Handles disconnections gracefully
- Typing indicators - Shows when the assistant is working
- Message queuing - Queues messages when disconnected and flushes on reconnect
- LID translation - Handles WhatsApp’s Locally IDentified (LID) JID format
- Group metadata sync - Automatically syncs group names every 24 hours
How it works
The WhatsApp channel implementation is insrc/channels/whatsapp.ts:
Architecture
Setup
WhatsApp is not bundled with NanoClaw’s core install. Add it using the/add-whatsapp skill:
skill/whatsapp branch into your fork, adding the WhatsApp channel code and its dependencies (including @whiskeysockets/baileys). The skill will then:
- Generate a QR code for WhatsApp Web authentication
- Wait for you to scan it with your phone
- Store authentication credentials in
store/auth/ - Connect to WhatsApp and verify the connection
If authentication fails or expires, run
/add-whatsapp again to re-authenticate.Configuration
Assistant has own number
Set this insrc/config.ts:
- You and the assistant share the same WhatsApp number
- Assistant messages are prefixed with the assistant name (e.g., “Andy: Hello!”)
- Required for self-chat (messaging yourself)
- The assistant has its own dedicated WhatsApp number
- No message prefix needed
- Cleaner appearance in group chats
Assistant name
The assistant name is used as the message prefix and trigger pattern:Connection settings
Connection logic is insrc/channels/whatsapp.ts:
Message handling
Bot message detection
The channel determines if a message came from the bot:Message prefix
Outgoing messages are prefixed unless using a dedicated number:Group metadata sync
Group names are synced from WhatsApp every 24 hours:JID format
WhatsApp uses JIDs (Jabber IDs) to identify chats:- Individual:
1234567890@s.whatsapp.net - Group:
120363012345678901@g.us - LID (newer format):
123456:78@lid
Registering chats
To make the assistant respond in a chat, register it:Main chat (self-chat)
Your self-chat is the admin control channel:Group chats
For WhatsApp groups:WhatsApp-specific skills
Several skills extend WhatsApp with media handling capabilities. These live on thenanoclaw-whatsapp fork as skill/* branches.
| Skill | Command | What it does |
|---|---|---|
| Voice transcription | /add-voice-transcription | Transcribe voice notes via Whisper API |
| Local whisper | /use-local-whisper | Offline transcription via whisper.cpp |
| Image vision | /add-image-vision | Understand image attachments |
| PDF reader | /add-pdf-reader | Extract text from PDF attachments |
| Emoji reactions | /add-reactions | Send, receive, and search emoji reactions |
Emoji reactions
The/add-reactions skill adds full emoji reaction support:
- Receive reactions: Reactions on messages are stored in a dedicated
reactionstable with a forward-only emoji state machine (sent → delivered → read → reacted) - Send reactions: A
react_to_messageMCP tool lets the agent react to specific messages - Search reactions: Query reactions by emoji, sender, or message
- Database migration: Adds a
reactionstable automatically on first run
Troubleshooting
Authentication expired
If you see “WhatsApp authentication required” notifications:Connection issues
The channel automatically reconnects on disconnection:Not receiving messages
Check if the chat is registered:Bot responding to itself
EnsureASSISTANT_HAS_OWN_NUMBER is set correctly in src/config.ts:
- If sharing a number, set to
false(bot messages will have the name prefix) - If using a dedicated number, set to
true(bot messages are identified byfromMe)
Using other channels
NanoClaw supports multiple messaging channels as equal options. You can run WhatsApp alongside other channels or use a different channel entirely.Add another channel
Remove WhatsApp
To remove the WhatsApp skill and revert to a channel-free core:Implementation details
Message queue
Messages sent while disconnected are queued and flushed on reconnect:Presence updates
The channel announces availability on connection:Source code reference
After installing the WhatsApp skill, the implementation lives in:src/channels/whatsapp.ts- Main WhatsAppChannel classsrc/config.ts- Configuration constants (extended by the skill)src/index.ts- Channel initialization and routing
These files are added by the
skill/whatsapp branch merge. They do not exist in NanoClaw’s core install.Next steps
Add Telegram
Add Telegram support alongside or instead of WhatsApp
Add Discord
Add Discord support to your installation