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.

Registration

After authentication, you register the chats where NanoClaw should be active. The skill supports three types:

• Self-chat — message yourself to trigger the agent. This is a common setup for personal use.
• Direct messages — register a specific contact’s DM.
• Group chats — register a WhatsApp group by its JID (group ID).

You can register multiple chats with different trigger configurations. For example, your self-chat could be the main channel while a family group is set to trigger-only mode.

Reconnection and stability

WhatsApp connections can occasionally drop, especially after phone software updates or long periods of inactivity. NanoClaw handles reconnections automatically with exponential backoff. 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 text messages, images, documents, voice notes (with the voice transcription skill), and replies with context.

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.