Skip to content

WHATSAPP_SETUP.md

Latest commit

 

History

History
206 lines (155 loc) · 7.46 KB

WHATSAPP_SETUP.md

File metadata and controls

206 lines (155 loc) · 7.46 KB
Raw

WhatsApp First-Party Integration Setup

OpenClaw supports direct WhatsApp connectivity via two driver engines: Baileys (Node.js) and whatsmeow (Go). Both provide the same features — text and media messaging, groups, reactions, read receipts, typing indicators, and QR/pairing code authentication — through different underlying libraries.

Prerequisites

Driver Runtime Required Notes
baileys Node.js 18+ Uses @whiskeysockets/baileys, an unofficial WhatsApp Web library
whatsmeow Pre-built binary or Go 1.21+ Uses whatsmeow, a Go WhatsApp Web library
simulated .NET 10 Test-only driver — records operations without connecting to WhatsApp

Quick Start

# Automated setup — detects runtimes, installs dependencies, builds binaries
scripts/setup-whatsapp.sh

Or manually:

# Baileys (Node.js)
cd src/whatsapp-baileys-worker
npm install

# whatsmeow (Go)
cd src/whatsapp-whatsmeow-worker
go build -o whatsapp-whatsmeow-worker .

Configuration

Add to appsettings.json:

{
  "Channels": {
    "WhatsApp": {
      "Enabled": true,
      "Type": "first_party_worker",
      "FirstPartyWorker": {
        "Driver": "baileys",
        "StoragePath": "./memory/whatsapp-worker",
        "Accounts": [
          {
            "AccountId": "default",
            "SessionPath": "./session/default",
            "PairingMode": "qr",
            "DeviceName": "OpenClaw"
          }
        ]
      }
    }
  }
}

Configuration Reference

FirstPartyWorker

Field Default Description
Driver "baileys_csharp" Engine: "baileys", "whatsmeow", "simulated", or "baileys_csharp"
ExecutablePath auto-detected Explicit path to the worker script/binary
WorkingDirectory auto Working directory for the worker process
StoragePath "./memory/whatsapp-worker" Root for session, media, and cache files
MediaCachePath {StoragePath}/media-cache Where downloaded media files are cached
HistorySync true Enable WhatsApp message history sync on first connect
Proxy none HTTP proxy URL for the WhatsApp connection
Accounts [] List of WhatsApp account configurations

Accounts[]

Field Default Description
AccountId "default" Unique identifier for this account
SessionPath "./session/default" Where session credentials are stored
DeviceName "OpenClaw" Device name shown in WhatsApp linked devices
PairingMode "qr" "qr" for QR code scan, "pairing_code" for 8-digit code
PhoneNumber none Required for pairing_code mode (E.164 format, e.g. "15551234567")
SendReadReceipts true Automatically mark inbound messages as read
AckReaction false Send an emoji reaction when a message is accepted
MediaCachePath inherited Per-account media cache override
HistorySync true Per-account history sync override
Proxy inherited Per-account proxy override

Authentication Flow

QR Code (default)

  1. Start the gateway with "PairingMode": "qr"
  2. The worker emits a qr_code auth event with the QR data
  3. View the QR code:
    • Admin UI: Navigate to the WhatsApp setup page
    • Companion app: The QR is displayed automatically
    • API: GET /admin/channels/whatsapp/auth-status
    • SSE stream: GET /admin/channels/{channelId}/auth/stream
  4. Scan the QR code with WhatsApp on your phone (Settings > Linked Devices > Link a Device)
  5. The worker emits a connected event with the account's JID

Pairing Code (headless)

For headless servers without a way to display QR codes:

  1. Set "PairingMode": "pairing_code" and "PhoneNumber": "15551234567"
  2. Start the gateway
  3. The worker requests a pairing code from WhatsApp and emits a pairing_code auth event
  4. On your phone, go to Settings > Linked Devices > Link a Device > Link with phone number
  5. Enter the 8-digit code shown in the admin UI or API response

Session Persistence

Credentials are stored at SessionPath and persist across restarts. You only need to pair once per account. If the session expires or you log out from your phone, re-pairing is required.

Multi-Account

Configure multiple entries in the Accounts array:

{
  "Accounts": [
    {
      "AccountId": "personal",
      "SessionPath": "./session/personal",
      "PairingMode": "qr"
    },
    {
      "AccountId": "business",
      "SessionPath": "./session/business",
      "PairingMode": "pairing_code",
      "PhoneNumber": "15559876543"
    }
  ]
}

Each account connects independently and has its own QR/pairing flow. Inbound messages are routed to the gateway pipeline from all accounts. Outbound messages are routed to the appropriate account based on recipient.

Media Handling

Both drivers support inbound and outbound media:

Inbound: Images, videos, audio (including voice notes), documents, and stickers are downloaded to MediaCachePath and passed to the gateway as [IMAGE_URL:file://...] markers in the message text.

Outbound: The gateway sends a BridgeMediaAttachment array with each outbound message. The worker downloads media from the provided URL and sends it via WhatsApp. Supported types: image, video, audio (sent as PTT voice note), document, sticker.

Driver Comparison

Feature Baileys (Node.js) whatsmeow (Go)
Language JavaScript/TypeScript Go
Library @whiskeysockets/baileys go.mau.fi/whatsmeow
Session storage Multi-file auth state (JSON files) SQLite database
Maturity Widely used, community-maintained Production-grade, used by Matrix bridge
Protocol stability Can break on WhatsApp updates Generally more stable
Memory usage Higher (Node.js overhead) Lower (native binary)
Build step npm install go build

Recommendation: Use whatsmeow for production deployments (more stable, lower resource usage). Use Baileys if you're already running Node.js or prefer the JavaScript ecosystem.

Troubleshooting

Worker not found

First-party WhatsApp worker executable was not found.

Run scripts/setup-whatsapp.sh or set ExecutablePath explicitly in the config.

Node.js not found (Baileys)

Node.js is required for the Baileys WhatsApp driver but was not found.

Install Node.js 18+ from https://nodejs.org/ or use the whatsmeow driver instead.

Dependencies not installed (Baileys)

Baileys worker dependencies not installed.

Run npm install in src/whatsapp-baileys-worker/.

Connection keeps dropping

WhatsApp may disconnect for various reasons:

  • Check your internet connection
  • Ensure your phone has WhatsApp open and connected
  • If using a proxy, verify the proxy is reachable
  • Check the gateway logs for disconnect reason codes

Session corruption

If authentication fails after a previous successful connection:

  1. Stop the gateway
  2. Delete the session directory (SessionPath)
  3. Restart and re-pair

Read receipts / reactions not working

Verify that your configuration has SendReadReceipts: true (the default). The bridge protocol sends the full message key (messageId + remoteJid + participant) required by both Baileys and whatsmeow. If receipts still fail, check the worker logs for JID parsing errors.