ClawdBotAI LogoClawdBotAI
HomeDocsChannelsWhatsApp

WhatsApp

WhatsApp Web via Baileys - Gateway owns the session(s)

Status: WhatsApp Web via Baileys only. Gateway owns the session(s).

Quick setup (beginner)

  1. Use a separate phone number if possible (recommended).
  2. Configure WhatsApp in ~/.clawdbot/clawdbot.json.
  3. Run clawdbot channels login to scan the QR code (Linked Devices).
  4. Start the gateway.

Minimal config:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}

Goals

  • Multiple WhatsApp accounts (multi-account) in one Gateway process.
  • Deterministic routing: replies return to WhatsApp, no model routing.
  • Model sees enough context to understand quoted replies.

Getting a phone number (two modes)

WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked.

Dedicated number (recommended)

Use a separate phone number for Clawdbot. Best UX, clean routing, no self-chat quirks.

Ideal setup: spare/old Android phone + eSIM. Leave it on Wi‑Fi and power, and link it via QR.

WhatsApp Business: You can use WhatsApp Business on the same device with a different number.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567"]
    }
  }
}

Personal number (fallback)

Quick fallback: run Clawdbot on your own number. Message yourself (WhatsApp "Message yourself") for testing.

{
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Number sourcing tips

  • Local eSIM from your country's mobile carrier (most reliable)
  • Austria: hot.at
  • UK: giffgaff — free SIM, no contract
  • Prepaid SIM — cheap, just needs to receive one SMS for verification
  • Avoid: TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively.

Tip: The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via creds.json.

Login + credentials

  • Login command: clawdbot channels login (QR via Linked Devices).
  • Multi-account login: clawdbot channels login --account <id>
  • Default account: default if present, otherwise the first configured account id.
  • Credentials stored in: ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json
  • Backup copy: creds.json.bak (restored on corruption).
  • Logout: clawdbot channels logout (or --account <id>)

Inbound flow (DM + group)

Gateway owns the Baileys socket and inbox loop. CLI / macOS app talk to the gateway; no direct Baileys use.

Personal-number mode (fallback)

Self-chat replies default to [{identity.name}] when set (otherwise [clawdbot]) if messages.responsePrefix is unset.

Read receipts

WhatsApp supports read receipts via sendReadReceipts config option.

Message normalization

What the model sees: messages are normalized with reply context and media placeholders.

Config quick map

Config KeyDescription
channels.whatsapp.dmPolicy"allowlist" | "pairing" | "open"
channels.whatsapp.allowFromArray of allowed phone numbers
channels.whatsapp.selfChatModeEnable self-chat mode for personal number
channels.whatsapp.configWritesAllow config updates via /config command

Troubleshooting

  • QR code not appearing: Ensure terminal supports QR display, or use --qr-code-in-terminal flag.
  • Session expired: Delete ~/.clawdbot/credentials/whatsapp/<id>/ and re-login.
  • Messages not received: Check clawdbot status and ensure Gateway is running.
  • Pairing not approved: Run clawdbot pairing list whatsapp and clawdbot pairing approve whatsapp <code>.
ChannelsTelegram