NanoClaw WhatsApp Bot: Setup, Features & Tips (2026 Guide)

Table of Contents

1. Why NanoClaw for WhatsApp?
2. Prerequisites
3. Setup Guide (7 Steps)
4. Key Features
5. Advanced Configuration
6. Tips & Best Practices
7. Troubleshooting
8. WhatsApp Bot Alternatives Comparison
9. Frequently Asked Questions

Why NanoClaw for WhatsApp?

WhatsApp is where conversations happen. Two billion users send messages through it every day, and for most people outside North America, it is the default communication channel for everything — work, family, side projects. The problem is that switching between WhatsApp and an AI tool every time you need help kills momentum. Copy a question, open Claude or ChatGPT in a browser, paste, wait, copy the answer, switch back to WhatsApp, paste again. It adds up.

NanoClaw's WhatsApp integration eliminates that loop entirely. It connects an AI assistant directly to your WhatsApp number so you can ask questions, analyze images, transcribe voice notes, and get intelligent responses without leaving the app. No browser tab. No context switching. Just message your AI like you message a friend.

What makes NanoClaw's approach different from other WhatsApp bots is the connection method. Most WhatsApp bot frameworks require a Meta Business account, an approved WhatsApp Business API application, and monthly fees starting around $50. NanoClaw uses the Baileys library instead — an open-source implementation of the WhatsApp Web protocol. That means any standard WhatsApp number works. No business verification. No API approval wait times. No per-message charges.

The trade-off is that Baileys operates outside Meta's official API, which means WhatsApp could theoretically block connections that look like automated traffic. In practice, NanoClaw handles this gracefully with rate limiting, human-like response delays, and session persistence that keeps connections stable for weeks at a time.

For teams, the group chat feature is particularly valuable. NanoClaw can join a WhatsApp group and respond only when mentioned by name — acting as a silent team member who answers questions on demand without flooding the conversation. Product teams, customer support groups, and study groups all benefit from having an AI participant that stays quiet until called upon.

This guide walks through the complete setup process, covers every major feature, and shares the configuration tips that keep the bot running reliably long-term.

Prerequisites

Before starting the NanoClaw WhatsApp setup, confirm the following are in place:

Hardware & Software

• Node.js 18 or later — NanoClaw and Baileys both require a modern Node.js runtime. Check your version with node --version in a terminal.
• A computer that stays on — The WhatsApp connection runs through your machine. If your computer sleeps or shuts down, the bot goes offline. A VPS, Raspberry Pi, or always-on desktop works best for 24/7 availability.
• Git installed — Required for cloning the NanoClaw repository.

WhatsApp Requirements

• A WhatsApp account — Either your personal number or a dedicated number. A second SIM or virtual number keeps your personal WhatsApp separate from the bot.
• WhatsApp linked devices available — WhatsApp allows up to four linked devices. The NanoClaw bot occupies one slot. If all four slots are full, unlink one before proceeding.
• Phone with WhatsApp installed — Required for the initial QR code scan. After pairing, the phone does not need to stay online.

API Keys

• An Anthropic API key — NanoClaw sends messages to Claude for processing. Create a key at console.anthropic.com. The Sonnet tier handles most WhatsApp conversations well at approximately $3 per million input tokens.
• Optional: OpenAI Whisper API key — Required only if you want voice message transcription. Without it, voice messages are ignored.

Estimated Costs

Total monthly cost for a personal WhatsApp AI assistant runs between $5 and $25 depending on usage volume and whether voice transcription is enabled.

Setup Guide

Step 1: Install NanoClaw

Clone the NanoClaw repository and install dependencies:

git clone https://github.com/nanoclaw/nanoclaw.git
cd nanoclaw
npm install

Create a .env file in the root directory with your API keys:

ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here  # Optional, for voice transcription
NANOCLAW_MODEL=claude-sonnet-4-20250514

Run the initial setup command to verify the installation:

npx nanoclaw --version

The output should display the current NanoClaw version (3.x or later). If you see an error about missing modules, delete node_modules and run npm install again.

Step 2: Run the /add-whatsapp Skill

NanoClaw uses a modular skill system. The WhatsApp integration is a separate skill that gets added to your base installation:

npx nanoclaw /add-whatsapp

This command does three things:

1. Downloads the WhatsApp skill package including the Baileys library
2. Creates a whatsapp/ directory inside your NanoClaw project with configuration files
3. Generates a default whatsapp-config.json with sensible defaults

After the skill installs, you should see a confirmation message listing the new files created. The most important one is whatsapp/whatsapp-config.json — that is where all customization happens.

Step 3: Scan the QR Code

Start the WhatsApp connection process:

npx nanoclaw whatsapp --pair

A QR code appears in your terminal. On your phone:

1. Open WhatsApp
2. Go to Settings > Linked Devices
3. Tap Link a Device
4. Point your camera at the terminal QR code

The terminal displays "Connected" once pairing succeeds. NanoClaw stores the session credentials in whatsapp/auth/ so you do not need to scan the QR code again unless you manually unlink the device or the session expires (typically after 14 days of inactivity).

Important: The QR code expires after 60 seconds. If it times out, press Enter in the terminal to generate a fresh one. If the QR code renders poorly in your terminal, try increasing your terminal width to at least 80 columns or use a terminal with Unicode support.

Step 4: Configure Group Settings

By default, NanoClaw responds to every direct message but stays silent in groups. To enable group chat functionality, edit whatsapp/whatsapp-config.json:

{
  "groups": {
    "enabled": true,
    "trigger": "@nanoclaw",
    "respondToAll": false,
    "allowedGroups": [],
    "blockedGroups": []
  }
}

Key options:

• enabled — Set to true to allow the bot to operate in group chats.
• trigger — The mention keyword that activates the bot. When someone types @nanoclaw what is the capital of France? in a group, the bot responds. Messages without the trigger are ignored.
• respondToAll — Set to true if you want the bot to respond to every message in allowed groups (use with caution — this floods group chats quickly).
• allowedGroups — An array of WhatsApp group JIDs. Leave empty to allow all groups. To find a group's JID, send a message in the group after enabling debug logging.
• blockedGroups — Groups where the bot should never respond, even if mentioned.

For most setups, enabling groups with a trigger keyword and leaving the allowedGroups array empty provides the right balance. The bot participates everywhere but only when asked.

Step 5: Set Up Media Handling

NanoClaw can analyze images, PDFs, and other documents sent via WhatsApp. Enable media handling in the config:

{
  "media": {
    "enabled": true,
    "maxFileSizeMB": 16,
    "supportedTypes": ["image/jpeg", "image/png", "image/webp", "application/pdf"],
    "autoAnalyze": true,
    "saveToLocal": false
  }
}

When someone sends a photo with a question like "What plant is this?" or forwards a PDF with "Summarize this document," NanoClaw downloads the media, sends it to Claude's vision API, and responds with the analysis.

The maxFileSizeMB setting caps file downloads at 16 MB by default. WhatsApp compresses most images to under 1 MB, but PDFs and documents can be larger. Increase this limit if your use case involves large files.

Setting saveToLocal to true stores all received media in a whatsapp/media/ directory. This is useful for logging but can consume significant disk space over time.

Step 6: Enable Voice Transcription

Voice messages are WhatsApp's most-used feature in many regions. NanoClaw transcribes them and responds to the spoken content:

{
  "voice": {
    "enabled": true,
    "provider": "whisper",
    "model": "whisper-1",
    "language": "auto",
    "respondToTranscription": true
  }
}

When a user sends a voice note, NanoClaw:

1. Downloads the audio file (.ogg format from WhatsApp)
2. Converts it to a compatible format using FFmpeg
3. Sends it to OpenAI's Whisper API for transcription
4. Passes the transcribed text to Claude for a response
5. Replies with both the transcription and the AI answer

FFmpeg is required for voice transcription. Install it:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg
• Windows: Download from ffmpeg.org and add to PATH

The language setting accepts ISO 639-1 codes (en, es, fr, de, etc.) or auto for automatic detection. Setting a specific language improves transcription accuracy for monolingual conversations.

Step 7: Test Your Bot

Start the bot in foreground mode to watch activity in real time:

npx nanoclaw whatsapp --start

Run through these tests:

1. Direct message test — Send a simple question from another phone or WhatsApp Web. Verify the bot responds within a few seconds.
2. Group mention test — Add the bot's number to a test group. Send a message with the trigger keyword. Confirm the bot responds only to triggered messages.
3. Image test — Send a photo with a question. Check that the bot analyzes the image and gives a relevant response.
4. Voice test — Send a short voice note asking a question. Confirm you get back a transcription and an answer.
5. Rate limit test — Send 10 messages rapidly. The bot should process them sequentially without crashing or duplicating responses.

If all five tests pass, the bot is fully operational. Run it as a background process for persistent availability:

npx nanoclaw whatsapp --start --daemon

Or use a process manager like PM2:

pm2 start "npx nanoclaw whatsapp --start" --name nanoclaw-whatsapp
pm2 save

PM2 automatically restarts the bot if it crashes and persists across server reboots.

Key Features

1. Direct Message AI Chat

The core feature. Send any text message to the bot's WhatsApp number and receive an AI-powered response. NanoClaw maintains conversation context within a session, so follow-up questions work naturally.

A conversation might look like:

You: What are the main differences between REST and GraphQL? NanoClaw: REST uses multiple endpoints with fixed data structures. GraphQL uses a single endpoint with flexible queries... You: Which one is better for a mobile app? NanoClaw: For mobile apps, GraphQL has advantages in bandwidth efficiency...

Context persists for 30 minutes by default (configurable via sessionTimeoutMinutes in the config). After the timeout, a new conversation starts fresh. This prevents old context from contaminating new questions.

2. Group Chat with Mention Triggers

In group settings, the bot operates in a listen-but-don't-speak mode until someone uses the trigger keyword. This design choice matters because group chats move fast, and an AI that responds to every message becomes noise.

The trigger system supports several patterns:

• Direct mention: @nanoclaw explain this error
• Quoted reply: Reply to any message and include @nanoclaw to analyze it
• Thread continuation: After the bot responds, any reply to the bot's message is treated as a follow-up (no trigger needed)

For teams, this turns WhatsApp groups into spaces where AI assistance is always one mention away. A developer can screenshot an error, tag the bot, and get a debugging suggestion without leaving the group conversation.

3. Image and Document Analysis

NanoClaw leverages Claude's vision capabilities through WhatsApp. Send an image and the bot describes, analyzes, or answers questions about it. Practical uses include:

• Receipt scanning — Photograph a receipt and ask "How much did I spend on groceries?"
• Code screenshots — Send a screenshot of code and ask "What's wrong with this function?"
• Document summaries — Forward a PDF and request a summary or key points extraction
• Plant/object identification — Point your camera at something and ask what it is
• Whiteboard capture — Photograph meeting notes and ask for a clean formatted version

PDF analysis works for documents up to the configured file size limit. The bot extracts text from the PDF, sends it to Claude, and returns the analysis as a WhatsApp message. For multi-page documents, the response includes page references.

4. Voice Message Transcription

Voice messages get transcribed and processed as text. The transcription appears as a quoted block in the response, followed by the AI's answer to whatever was spoken. This serves two purposes: it creates a text record of voice messages (useful for searchability), and it lets the AI respond to spoken questions just as effectively as typed ones.

Whisper handles multiple languages and accents reliably. For multilingual groups, setting language to auto allows the bot to detect and transcribe messages in different languages within the same group.

Transcription accuracy sits at roughly 95% for clear audio in supported languages. Background noise, crosstalk, and heavy accents reduce accuracy. The bot includes a confidence indicator when transcription quality drops below a threshold.

5. Scheduled Messages

NanoClaw can send automated messages at scheduled times. Configure schedules in the config file:

{
  "scheduled": [
    {
      "chatId": "1234567890@s.whatsapp.net",
      "message": "Daily standup reminder: Post your updates in the thread.",
      "cron": "0 9 * * 1-5"
    },
    {
      "chatId": "9876543210-group@g.us",
      "message": "Weekly report time. What did everyone ship this week?",
      "cron": "0 17 * * 5"
    }
  ]
}

Schedules use standard cron syntax. Common use cases include daily standup reminders, weekly report prompts, recurring check-in messages for accountability groups, and automated good-morning messages with a daily AI-generated tip or fact.

The scheduler runs inside the NanoClaw process, so no external cron daemon is needed. Messages send at the specified times as long as the bot is running and connected.

6. Multi-Device Support

A single NanoClaw installation can manage multiple WhatsApp numbers simultaneously. Each number runs as a separate session with its own configuration:

npx nanoclaw whatsapp --pair --session personal
npx nanoclaw whatsapp --pair --session work
npx nanoclaw whatsapp --start --session all

Each session maintains independent conversation history, group settings, and media preferences. This matters for users who separate personal and work WhatsApp accounts or manage bots for different teams.

Session data is stored in isolated directories under whatsapp/sessions/, keeping credentials and conversation logs separate. Switching between sessions or running them all simultaneously does not cause cross-contamination.

Advanced Configuration

Custom Triggers and Commands

Beyond the basic mention trigger, NanoClaw supports custom command prefixes:

{
  "commands": {
    "prefix": "!",
    "list": {
      "summarize": "Summarize the last 20 messages in this group",
      "translate": "Translate the following message to English",
      "remind": "Set a reminder. Usage: !remind [time] [message]",
      "help": "List all available commands"
    }
  }
}

Users type !summarize or !translate Hola mundo and the bot executes the corresponding action. Custom commands pair a keyword with a system prompt that shapes the AI's response. Add as many as your workflow demands.

Rate Limiting

Protect your API budget and avoid WhatsApp's anti-spam detection with rate limits:

{
  "rateLimits": {
    "messagesPerMinute": 10,
    "messagesPerHour": 100,
    "messagesPerDay": 500,
    "perUserPerMinute": 3,
    "cooldownMessage": "Slow down. Try again in a moment."
  }
}

The perUserPerMinute setting prevents a single person from spamming the bot in a group. When someone exceeds the limit, the bot sends the cooldown message once and ignores further messages until the window resets.

Global limits (messagesPerHour, messagesPerDay) act as circuit breakers for API cost control. At approximately $0.003 per message with Sonnet, 500 daily messages cost about $1.50 — but unexpected viral usage in a large group can spike costs without limits in place.

Privacy Settings

Control what the bot stores and who can interact with it:

{
  "privacy": {
    "allowedContacts": [],
    "blockedContacts": [],
    "logMessages": false,
    "logMediaMetadata": false,
    "deleteMediaAfterProcessing": true,
    "encryptLocalStorage": true
  }
}

• allowedContacts — Whitelist specific phone numbers. When populated, the bot ignores everyone else. Leave empty to allow all contacts.
• blockedContacts — Blacklist specific numbers. Takes priority over allowedContacts.
• logMessages — When false, message content is not saved to disk. Only session metadata is stored.
• deleteMediaAfterProcessing — Removes downloaded images, PDFs, and voice notes immediately after analysis. Prevents sensitive content from lingering on the server.
• encryptLocalStorage — Encrypts session data and any cached content using AES-256. Adds a small performance overhead but protects data at rest.

For compliance-sensitive environments (healthcare, legal, finance), set all logging to false, enable media deletion, and encrypt local storage. The bot still functions fully — it just does not keep records.

Tips and Best Practices

1. Use a Dedicated Phone Number

Running the bot on your personal WhatsApp number works but creates friction. Friends and family message you expecting a human reply, and the bot responds first. A prepaid SIM or virtual number (Google Voice, Twilio, or a local eSIM provider) keeps the bot separate. Cost: $1-5/month for a virtual number.

2. Set a System Prompt That Matches the Context

The default NanoClaw system prompt is generic. Customize it for your use case:

{
  "systemPrompt": "You are a helpful AI assistant on WhatsApp. Keep responses concise — under 300 words. Use short paragraphs. Avoid markdown formatting since WhatsApp renders it poorly. When you don't know something, say so directly."
}

WhatsApp has its own formatting rules (single asterisks for bold, underscores for italic). Standard markdown headers, code blocks, and bullet lists do not render well. A system prompt that instructs the AI to use WhatsApp-friendly formatting dramatically improves readability.

3. Enable Response Chunking for Long Answers

WhatsApp messages have a practical display limit around 4,096 characters. Long AI responses get cut off or appear as walls of text. Enable chunking to split long responses into multiple messages:

{
  "response": {
    "maxLength": 3000,
    "chunkOnParagraph": true,
    "delayBetweenChunks": 1500
  }
}

The delayBetweenChunks setting (in milliseconds) adds a human-like pause between message parts, reducing the bot's appearance as automated traffic.

4. Monitor Connection Health

Baileys connections occasionally drop due to network interruptions, WhatsApp server updates, or session token expiration. Set up health monitoring:

npx nanoclaw whatsapp --health

This command returns connection status, uptime, message counts, and last activity timestamp. For automated monitoring, NanoClaw supports webhook notifications when the connection drops:

{
  "webhooks": {
    "onDisconnect": "https://your-server.com/alerts/whatsapp-down",
    "onReconnect": "https://your-server.com/alerts/whatsapp-up"
  }
}

Pair this with a simple uptime monitor (UptimeRobot, Healthchecks.io) to get SMS or email alerts when the bot goes offline.

5. Rotate API Models Based on Message Type

Not every WhatsApp message needs the most expensive model. Configure model routing to optimize cost:

{
  "modelRouting": {
    "default": "claude-sonnet-4-20250514",
    "image": "claude-sonnet-4-20250514",
    "complex": "claude-opus-4-20250514",
    "simple": "claude-haiku-3-20250307"
  }
}

Short factual questions route to Haiku (cheapest). Image analysis goes to Sonnet (best balance). Complex multi-step reasoning triggers Opus (most capable). NanoClaw classifies incoming messages automatically based on length, presence of media, and conversation history depth.

6. Back Up Session Credentials

The whatsapp/auth/ directory contains your session credentials. If these are lost, you need to re-scan the QR code and all existing sessions reset. Back up this directory:

# Simple backup
cp -r whatsapp/auth/ whatsapp/auth-backup-$(date +%Y%m%d)/

# Or add to your existing backup system

For server deployments, include the auth directory in your infrastructure backup rotation. Session files are small (under 1 MB) and change infrequently, so differential backups work efficiently.

Troubleshooting

1. QR Code Not Appearing

Symptom: Running npx nanoclaw whatsapp --pair shows a blank terminal or garbled characters instead of a QR code.

Fix: Your terminal does not support Unicode block characters. Try:

• Switch to a modern terminal (Windows Terminal, iTerm2, Alacritty)
• Set terminal encoding to UTF-8: export LANG=en_US.UTF-8
• Add the --qr-png flag to save the QR code as an image file instead: npx nanoclaw whatsapp --pair --qr-png
• Increase terminal font size — small fonts make QR codes unscannable

2. Connection Drops After a Few Hours

Symptom: The bot works initially but disconnects after 2-6 hours.

Fix: This usually indicates a session persistence issue. Verify:

• The whatsapp/auth/ directory has write permissions
• No antivirus or firewall is blocking persistent WebSocket connections
• The machine is not going to sleep (disable sleep mode or use caffeinate on macOS)
• Add "keepAliveIntervalMs": 30000 to the config to send heartbeat packets every 30 seconds
• If on a VPS, check that the provider allows long-lived WebSocket connections (some free tiers terminate them)

3. Bot Responds Twice to the Same Message

Symptom: Every incoming message triggers two identical responses.

Fix: This happens when two NanoClaw instances are running simultaneously. Check for duplicate processes:

ps aux | grep nanoclaw
# Kill duplicates
kill [PID]

If using PM2, verify only one WhatsApp instance is registered: pm2 list. Also check that you are not running both --daemon mode and a foreground instance.

4. Voice Messages Are Not Transcribed

Symptom: The bot ignores voice notes entirely or responds with an error.

Fix: Verify these items in order:

1. FFmpeg is installed and accessible: ffmpeg -version
2. The OpenAI API key is set in .env and has Whisper API access
3. Voice transcription is enabled in the config (voice.enabled: true)
4. The voice note file size is within limits (WhatsApp voice notes are typically under 5 MB)
5. Disk space is available for temporary audio file storage during conversion

The most common cause is a missing FFmpeg installation. The bot silently skips voice messages without it.

5. High API Costs

Symptom: Anthropic API bill is higher than expected.

Fix: Review usage patterns:

• Check npx nanoclaw whatsapp --stats for message volume by user and group
• Enable rate limits if not already active (see Advanced Configuration)
• Switch simple queries to Haiku using model routing
• Reduce sessionTimeoutMinutes to prevent long conversation contexts that increase token usage per message
• Disable autoAnalyze for media if image analysis is driving cost — require an explicit question with each image instead

A typical personal user sending 50-100 messages per day should see $5-15/month in API costs with Sonnet. If costs exceed that, group chat usage without per-user rate limits is usually the culprit.

WhatsApp Bot Alternatives

NanoClaw stands out for personal and small-team use because the total cost stays under $20/month and setup requires no coding beyond editing a JSON config file. The unofficial API approach means no Meta business verification, which alone saves weeks of waiting.

Twilio + Custom Code is the enterprise choice. Official API compliance, guaranteed uptime SLAs, and webhook-based architecture make it reliable for customer-facing bots. The trade-off is that you build everything from scratch — message routing, AI integration, conversation state management, and error handling are all your responsibility.

WAHA targets developers who want a REST API wrapper around Baileys. It provides HTTP endpoints for sending and receiving WhatsApp messages but includes no AI features. Pair it with any language model API for a custom solution. More flexible than NanoClaw but requires significantly more development effort.

Wassenger and Chatbot.team are managed services for businesses that need official WhatsApp API access without building infrastructure. Higher monthly costs but lower maintenance burden. Best suited for customer support and marketing automation rather than personal AI assistant use cases.

For the majority of individuals and small teams who want an AI assistant on WhatsApp today, NanoClaw offers the fastest path from zero to working bot with the lowest ongoing cost.

Frequently Asked Questions

Is NanoClaw WhatsApp bot free to use?

NanoClaw itself is free and open source. The costs come from the AI API — Anthropic charges per token for Claude access. Typical personal usage runs $5-15/month depending on message volume. Voice transcription through OpenAI Whisper adds a small additional cost ($0.006 per minute of audio). There are no WhatsApp-specific fees since NanoClaw uses the Baileys library instead of the paid WhatsApp Business API.

Will my WhatsApp account get banned for using NanoClaw?

The risk is low but not zero. NanoClaw uses the Baileys library, which connects through the WhatsApp Web protocol rather than the official Business API. WhatsApp's terms of service prohibit unofficial API usage. In practice, NanoClaw mitigates detection by implementing rate limiting, human-like response delays, and stable session management. Thousands of users run Baileys-based bots without issues. Using a dedicated number rather than your primary personal account is the safest approach.

Can NanoClaw work in WhatsApp group chats?

Yes. NanoClaw supports group chats with configurable mention triggers. The bot joins a group and stays silent until someone mentions its trigger keyword (default: @nanoclaw). It can be restricted to specific groups via the allowedGroups config, and it supports thread-based follow-up conversations where replies to the bot's messages do not require the trigger keyword.

How does NanoClaw handle voice messages on WhatsApp?

NanoClaw downloads the voice note, converts the audio format using FFmpeg, sends it to OpenAI's Whisper API for transcription, then passes the transcribed text to Claude for a response. The reply includes both the transcription (so the sender can verify accuracy) and the AI's answer. Automatic language detection works for over 50 languages. FFmpeg must be installed on the host machine for this feature to function.

Can I use NanoClaw WhatsApp bot on multiple devices?

Yes. A single NanoClaw installation supports multiple WhatsApp sessions running simultaneously. Each session connects to a different WhatsApp number with its own QR pairing, configuration, and conversation history. Run npx nanoclaw whatsapp --pair --session [name] for each additional number. All sessions can be started together with --session all.

What happens if my server goes offline?

Messages sent to the bot while the server is offline are queued by WhatsApp. When NanoClaw reconnects, it processes queued messages in order — though responses to old messages may feel out of context. The bot automatically reconnects when the server comes back online. For critical availability, use PM2 or systemd to auto-restart the process after crashes, and set up health check webhooks for disconnect alerts.