Skip to main content
PicoClaw supports WhatsApp integration in two modes: native (recommended) using whatsmeow, or bridge mode connecting to an external WebSocket bridge.

​
Integration Modes

  • In-process integration using whatsmeow
  • No separate bridge server needed
  • QR code authentication on first run
  • Session persistence across restarts
  • Requires building with -tags whatsapp_native

​
Bridge Mode

  • Connect to external WebSocket bridge
  • Useful if you already have a WhatsApp bridge running
  • Requires separate bridge server setup
  • More complex deployment
Native mode is optional to keep the default binary small. You need to build PicoClaw with WhatsApp support enabled, or use a pre-built binary with native support.

​
Prerequisites

  • WhatsApp account on your phone
  • PicoClaw installed with LLM provider configured
  • For native mode: PicoClaw built with -tags whatsapp_native

​
Native Mode Setup

1

Build with WhatsApp Support

Native WhatsApp support is optional. Build PicoClaw with the native tag:
# Using make
make build-whatsapp-native

# Or directly with go
go build -tags whatsapp_native ./cmd/picoclaw
The binary will include native WhatsApp integration.
If you downloaded a pre-built binary, check if it includes WhatsApp support by running picoclaw gateway with WhatsApp enabled. If it shows an error about missing support, rebuild with the tag.
2

Configure Native Mode

Edit ~/.picoclaw/config.json:
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}
FieldValueDescription
enabledtrueEnable WhatsApp channel
use_nativetrueUse native whatsmeow integration
session_store_path""Leave empty to use <workspace>/whatsapp/
allow_from[]List of allowed phone numbers (empty = allow all)
If session_store_path is empty, sessions are stored in ~/.picoclaw/workspace/whatsapp/ by default.
3

Start Gateway and Scan QR Code

Run the Gateway:
picoclaw gateway
On first run, a QR code will be printed in the terminal:
[INFO] whatsapp: Starting native WhatsApp client
[INFO] whatsapp: No session found, please scan QR code:

████████████████████████████████
██ ▄▄▄▄▄ █▀ █▀▀██  █ ▄▄▄▄▄ ██
██ █   █ █▀█  ▀▄ ▀█ █ █   █ ██
██ █▄▄▄█ ██▄▀ ▄▀▀ █ █▄▄▄█ ██
...
  1. Open WhatsApp on your phone
  2. Go to Settings → Linked Devices
  3. Tap Link a Device
  4. Scan the QR code from the terminal
  5. Wait for connection confirmation
4

Verify Connection

After successful scanning, you’ll see:
[INFO] whatsapp: Connected successfully
[INFO] whatsapp: Session saved to workspace/whatsapp/
Your WhatsApp bot is now ready! Send a message to the linked account to test.

​
Bridge Mode Setup

1

Set Up WhatsApp Bridge

Bridge mode requires a separate WebSocket bridge server. Popular options:Set up your bridge server to listen on a WebSocket endpoint (e.g., ws://localhost:3001).
2

Configure Bridge Mode

Edit ~/.picoclaw/config.json:
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": false,
      "bridge_url": "ws://localhost:3001",
      "allow_from": []
    }
  }
}
FieldValueDescription
enabledtrueEnable WhatsApp channel
use_nativefalseUse bridge mode
bridge_urlWebSocket URLBridge server endpoint
allow_fromArray of numbersAllowed phone numbers (optional)
3

Start Gateway

Ensure your bridge server is running, then start PicoClaw:
picoclaw gateway
The gateway will connect to your bridge via WebSocket.

​
Configuration Options

​
Native Mode Configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": ["+1234567890", "+9876543210"]
    }
  }
}
FieldTypeRequiredDescription
enabledbooleanYesEnable WhatsApp channel
use_nativebooleanYesSet to true for native mode
session_store_pathstringNoSession storage path (default: <workspace>/whatsapp/)
allow_fromarrayNoAllowed phone numbers in international format

​
Bridge Mode Configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": false,
      "bridge_url": "ws://localhost:3001",
      "allow_from": []
    }
  }
}
FieldTypeRequiredDescription
enabledbooleanYesEnable WhatsApp channel
use_nativebooleanYesSet to false for bridge mode
bridge_urlstringYesWebSocket URL of bridge server
allow_fromarrayNoAllowed phone numbers

​
Access Control

Allow specific numbers: 
{
  "allow_from": ["+1234567890", "+9876543210"]
}
Use international format: +[country code][number] Allow everyone: 
{
  "allow_from": []
}
Allowing all users means anyone with your WhatsApp number can use your bot, potentially incurring API costs.

​
Features

​
Text Messages

Send and receive text messages with full conversation context.

​
Group Chats

Bot can participate in WhatsApp groups (if invited and allowed by allow_from).

​
Media Support

Depending on your bridge/native implementation:
  • Image recognition (with vision-capable LLM)
  • Document handling
  • Voice message transcription (with Groq/Whisper)

​
Session Persistence

In native mode, the session is saved to disk. After the initial QR scan:
  • Subsequent restarts don’t require re-scanning
  • Session remains valid unless you unlink the device
  • Sessions are stored in <workspace>/whatsapp/

​
Troubleshooting

​
”WhatsApp native support not enabled”

Cause: PicoClaw binary doesn’t include WhatsApp native support Solution: Rebuild with the native tag: 
make build-whatsapp-native
# or
go build -tags whatsapp_native ./cmd/picoclaw

​
QR Code Not Displaying

Possible causes:
  1. Terminal doesn’t support QR code rendering
  2. Configuration has use_native: false
  3. Session already exists (check <workspace>/whatsapp/)
Solution:
  • Verify use_native: true in config
  • Delete existing session files to force re-authentication
  • Use a different terminal emulator

​
”Connection Closed” or Disconnected

Possible causes:
  1. WhatsApp unlinked the device
  2. Phone is offline
  3. Session expired
Solution:
  1. Check WhatsApp → Settings → Linked Devices
  2. Ensure your phone has internet connection
  3. Delete session and re-scan QR code: 
    rm -rf ~/.picoclaw/workspace/whatsapp/
picoclaw gateway

​
Bridge Mode Connection Failed

Check:
  1. Bridge server is running
  2. bridge_url is correct
  3. Network connectivity between PicoClaw and bridge
  4. Bridge logs for errors

​
Bot Doesn’t Respond

Possible causes:
  1. Number not in allow_from list
  2. LLM provider issues
  3. Session disconnected
Solution:
  • Check allow_from configuration
  • Test LLM with picoclaw agent -m "test"
  • Review Gateway logs for errors

​
Privacy & Security

Security Considerations:
  • WhatsApp sessions grant access to your account
  • Session files contain authentication credentials
  • Protect the workspace/whatsapp/ directory
  • Use allow_from to restrict access
  • Never share session files
  • Monitor linked devices in WhatsApp settings

​
Best Practices

  1. Session Storage: Keep session_store_path secure with proper file permissions
  2. Access Control: Always use allow_from for personal bots
  3. Regular Audits: Check linked devices periodically in WhatsApp
  4. Backup: Back up session files if you don’t want to re-scan QR codes
  5. Monitoring: Review Gateway logs for unexpected activity

​
Complete Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key"
    }
  ],
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": ["+1234567890"]
    }
  }
}

​
Next Steps

Telegram Channel

Simpler setup for testing

Discord Channel

Team collaboration platform

QQ Channel

Popular in China

Configuration

Advanced configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us