AI Tools Review

Insights

Moltbot WhatsApp Setup: The Ultimate 2026 Guide

AI Tools Review Editorial TeamJan 29, 2026
Moltbot WhatsApp Setup: The Ultimate 2026 Guide

    WhatsApp is the world's most popular messaging platform, making it the ideal "pocket" interface for a Moltbot assistant. By leveraging the Baileys gateway, Moltbot connects to WhatsApp Web, allowing an AI agent to send and receive messages, media, and even voice notes.

    This guide covers everything from sourcing a dedicated number to setting up advanced auto-reactions and securing the bot with pairing codes.

    Security Notice

    Setting up a messaging integration involves security-sensitive configurations including bot tokens, access controls, and permissions. Always verify configurations against the official documentation and follow security best practices. For the most up-to-date and authoritative guidance, consult the official Moltbot Channels documentation.

    Moltbot on WhatsApp

    The WhatsApp channel uses WhatsApp Web via Baileys. The Gateway owns the session(s), providing deterministic routing where replies always return to WhatsApp, the model never chooses channels.

    The Gateway Advantage

    • No 24-hour window: Initiate conversations whenever needed (unlike official Business API).
    • Full media support: Send/receive images, audio, documents, and voice notes.
    • Native feel: Works exactly like a normal contact or group participant.
    • Multi-account: Run multiple WhatsApp identities from one Gateway process.

    Quick Setup (Beginner)

    1. 1

      Use a Separate Phone Number

      If possible, use a dedicated number (recommended). This avoids self-chat quirks.

    2. 2

      Configure WhatsApp

      Add WhatsApp settings to ~/.clawdbot/moltbot.json.

    3. 3

      Login & Scan QR

      Run moltbot channels login and scan the QR code via Linked Devices.

    4. 4

      Start the Gateway

      Run moltbot gateway to begin listening for messages.

    Minimal Config

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

    Architecture (Who Owns What)

    Gateway Owns the Socket

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

    Active Listener Required

    An active listener is required for outbound sends; otherwise sends fail fast.

    Multi-Account Support

    Multiple WhatsApp accounts can run in one Gateway process via channels.whatsapp.accounts.

    Getting a Phone Number

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

    Trusted Number Sources

    Recommended

    • Local eSIM from a mobile carrier (most reliable)
    • Prepaid SIMcheap, just needs one SMS
    • Austria: hot.at
    • UK: giffgaff, free SIM, no contract
    • WhatsApp Businessuse on same device with different number

    Avoid

    • Google Voice / TextNow
    • "Free SMS" verification sites
    • Most VoIP providers

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

    Why Not Twilio?

    Early Moltbot builds supported Twilio's WhatsApp Business integration. However, WhatsApp Business numbers are a poor fit for a personal assistant: Meta enforces a 24-hour reply window, and high-volume usage triggers aggressive blocking. Support was removed due to unreliable delivery.

    Dedicated vs. Personal Number

    Dedicated Number

    The Gold Standard. Use a separate phone number for Moltbot. Best UX, clean routing, no self-chat quirks.

    • Clean session routing
    • Professional bot identity
    • Easy to share with others
    {
  "whatsapp": {
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

    Personal Number

    The Fallback. Run Moltbot on your own number via "Message yourself" for testing.

    • No extra cost
    • Instant setup
    • Requires selfChatMode: true
    {
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

    Login & Credentials

    Login Commands

    • moltbot channels loginQR via Linked Devices
    • moltbot channels login --account <id>Multi-account login
    • moltbot channels logoutDeletes WhatsApp auth state

    Credential Storage

    • Stored in ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json
    • Backup copy at creds.json.bak (restored on corruption)
    • Logged-out socket → error instructs re-link

    Inbound Flow (DM + Group)

    WhatsApp events come from messages.upsert (Baileys). Status/broadcast chats are ignored. Direct chats use E.164; groups use group JID.

    DM Policy Options

    • pairing (default), unknown senders get a pairing code
    • allowlistonly users in allowFrom permitted
    • openrequires allowFrom: ["*"]
    • disabledno DMs accepted

    Your linked WhatsApp number is implicitly trusted and skips policy checks.

    Message Normalization

    What the model sees:

    • Body with envelope context
    • Quoted reply context appended
    • Media placeholders: <media:image|video|audio>

    Group Chat Management

    Groups map to agent:<agentId>:whatsapp:group:<jid> sessions. Group policy: open | disabled | allowlist (default: allowlist).

    Group Activation Modes

    Send these as standalone messages in the group (Owner only):

    /activation mention

    Bot only replies when @mentioned (Default).

    /activation always

    Bot listens to every message in the thread.

    Owner = allowFrom (or self E.164 if unset). History injection: Recent unprocessed messages (default 50) inserted for context.

    Acknowledgment Reactions

    WhatsApp can automatically send emoji reactions to incoming messages immediately upon receipt, before the bot generates a reply. This provides instant feedback.

    {
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      }
    }
  }
}

    Options:

    • emojiEmoji to use (e.g. "👀", "✅"). Empty = disabled.
    • direct (default: true), Send reactions in DM chats.
    • group"always" | "mentions" | "never" (default: "mentions")

    Reactions are fire-and-forget; failures don't prevent the bot from replying.

    Voice Notes & Media

    Moltbot treats WhatsApp Voice Notes as native audio items. It will automatically rewrite OGG/Opus files to ensure they display as playable voice bubbles (PTT).

    Inbound Audio

    Voice notes are saved and can be transcribed via configuration. Best format: OGG/Opus.

    Outbound Audio

    Audio sent as PTT; audio/ogg → audio/ogg; codecs=opus. Appears as voice bubble.

    Animated GIFs

    WhatsApp expects MP4 with gifPlayback: true for inline looping. CLI: moltbot message send --media <mp4> --gif-playback

    Read Receipts

    By default, the gateway marks inbound WhatsApp messages as read (blue ticks) once accepted.

    {
  "channels": {
    "whatsapp": {
      "sendReadReceipts": false
    }
  }
}

    Note: Self-chat mode always skips read receipts. Per-account override available via accounts.<id>.sendReadReceipts.

    Limits & Chunking

    Message Limits

    • Outbound text: textChunkLimit (default 4000)
    • Inbound media: mediaMaxMb (default 50 MB)
    • Outbound media: agents.defaults.mediaMaxMb (default 5 MB)

    Chunking Options

    • chunkMode: "length" (default)
    • chunkMode: "newline"split on paragraph boundaries

    Images are auto-optimized to JPEG under cap (resize + quality sweep).

    Heartbeats & Reconnect

    Gateway Heartbeat

    Logs connection health via web.heartbeatSeconds (default 60s). Agent heartbeat can be configured per agent or globally.

    Reconnect Policy

    Backoff policy via web.reconnect: initialMs, maxMs, factor, jitter, maxAttempts. If maxAttempts reached, web monitoring stops (degraded).

    Full Config Reference

    {
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "selfChatMode": false,
      "allowFrom": ["+15551234567"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15559876543"],
      "sendReadReceipts": true,
      "textChunkLimit": 4000,
      "chunkMode": "length",
      "mediaMaxMb": 50,
      "historyLimit": 50,
      "dmHistoryLimit": 100,
      "configWrites": true,
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": "mentions"
      },
      "groups": {
        "*": { "requireMention": true }
      },
      "actions": {
        "reactions": true
      },
      "accounts": {
        "default": {
          "authDir": "~/.clawdbot/credentials/whatsapp/default",
          "mediaMaxMb": 50,
          "sendReadReceipts": true
        }
      }
    }
  },
  "web": {
    "enabled": true,
    "heartbeatSeconds": 60,
    "reconnect": {
      "initialMs": 1000,
      "maxMs": 30000,
      "factor": 2,
      "jitter": 0.1,
      "maxAttempts": 10
    }
  }
}

    Troubleshooting

    Conclusion

    Setting up Moltbot with WhatsApp bridges the gap between powerful AI and everyday mobile experience. Whether running a local node or using a dedicated Mac Mini, the WhatsApp channel provides the most accessible way to talk to an agent.

    Start with an allowlisted personal number for testing, then graduate to a dedicated number with auto-reactions and group activation as Moltbot becomes more deeply integrated into the workflow.

    Frequently Asked Questions

    Will Moltbot message random contacts when I link WhatsApp?
    No. Default DM policy is pairing, so unknown senders only get a pairing code and their message is not processed. Moltbot only replies to chats it receives, or to sends explicitly triggered.
    Can I use WhatsApp Business?
    Yes! It's recommended. Install WhatsApp Business on your phone with a second number and link that to Moltbot. Great for keeping personal WhatsApp separate.
    Why can't I use Twilio or a virtual number?
    WhatsApp is aggressive about blocking virtual numbers. Official APIs (like Twilio) are restrictive with 24-hour reply windows and don't support the agentic nature of Moltbot.
    Does it support blue ticks (read receipts)?
    By default, yes (sendReadReceipts: true). Disable to keep messages 'Unread' until manually checked. Self-chat mode always skips read receipts.
    Can multiple people use different Moltbots on one WhatsApp number?
    Yes, by routing each sender to a different agent via bindings (peer kind: 'dm', sender E.164). DM access control is global per WhatsApp account.
    Why do you ask for my phone number in the wizard?
    The wizard uses it to set the allowlist/owner so DMs are permitted. It's not used for auto-sending. If running on a personal number, use that same number and enable selfChatMode.

    Explore more AI tool comparisons

    In-depth reviews, benchmarks and guides to help you choose the right AI tools.

    Browse all reviews
    AI Tools Review Editorial Team

    AI Tools Review Editorial Team Expert verified

    Our editorial team consists of veteran AI researchers, software engineers, and industry analysts. We spend hundreds of hours benchmarking frontier models natively to provide you with objective, actionable intelligence on agentic AI capabilities and cybersecurity landscapes.