WhatsApp

How it works

The /add-whatsapp skill connects NanoClaw to WhatsApp using the multi-device API. This means the connection runs independently from your phone — your phone can be offline and NanoClaw will still receive and respond to messages.

The skill starts with pre-flight checks. It detects whether you’re running on a headless server or a desktop with a browser, because this affects which authentication method is available. Then it verifies that the necessary code and dependencies are in place, installing anything that’s missing.

Authentication happens in one of three ways. If you have a browser available, the skill opens a page with a QR code — you scan it with WhatsApp on your phone, just like linking WhatsApp Web. If you’re on a headless server, the QR code is rendered directly in the terminal using ASCII characters. The third option is pairing codes: you enter your phone number and get a numeric code to type into WhatsApp’s “Link a Device” screen. All three methods result in the same persistent session.

Once authenticated, the skill saves the session credentials locally. On future restarts, NanoClaw reconnects automatically without needing to re-scan or re-pair. The credentials live in store/auth/ and persist across reboots.

Wiring chats

After authentication, the skill asks whether the number is shared (your personal WhatsApp) or dedicated to the assistant — for a dedicated number it sets the optional ASSISTANT_HAS_OWN_NUMBER=true in .env. WhatsApp groups are auto-discovered and synced to the database, and you wire chats to agent groups with /manage-channels (or during /setup via the first-agent flow). Typical chats to wire:

• Self-chat — message yourself to talk to the agent. This is a common setup for personal use.
• Direct messages — a specific contact’s DM (<phone>@s.whatsapp.net).
• Group chats — a WhatsApp group by its JID (<id>@g.us).

Each wiring gets an unknown-sender policy and a session mode, and you can wire different chats to different agent groups when their contexts should stay isolated.

Reconnection and stability

WhatsApp connections can occasionally drop, especially after phone software updates or long periods of inactivity. NanoClaw handles reconnections automatically, retrying every few seconds. If a session becomes permanently invalid (you unlinked the device from your phone, for example), the logs will show a clear authentication error and you can re-run the skill to re-authenticate.

The Baileys library that powers this connection uses the same protocol as WhatsApp Web. It supports Markdown-formatted text messages, images, video, audio, documents, emoji reactions, and typing indicators.

Tips

• If you see “conflict” disconnection errors, it means another WhatsApp Web session took over. NanoClaw can only maintain one active Web session per phone number.
• The QR code expires after about 60 seconds. If it expires, the skill generates a new one automatically.
• For the most reliable setup on servers, use the pairing code method — it doesn’t require rendering a QR code and works well over SSH.
• WhatsApp has stricter rate limits than Telegram or Discord. NanoClaw respects these automatically, but very long agent responses may be split across multiple messages.