Setting Up Moltbot with WhatsApp: The Ultimate Guide (2026)

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
Use a Separate Phone Number
If possible, use a dedicated number (recommended). This avoids self-chat quirks.
2
Configure WhatsApp
Add WhatsApp settings to ~/.clawdbot/moltbot.json.
3
Login & Scan QR
Run moltbot channels login and scan the QR code via Linked Devices.
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 SIM — cheap, just needs one SMS
Austria: hot.at
UK: giffgaff — free SIM, no contract
WhatsApp Business — use 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"]
  }
}

moltbot channels login — QR via Linked Devices
moltbot channels login --account <id> — Multi-account login
moltbot channels logout — Deletes 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
allowlist — only users in allowFrom permitted
open — requires allowFrom: ["*"]
disabled — no 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:

emoji — Emoji 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
    }
  }
}

WhatsApp FAQ

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.

Setting Up Moltbot with WhatsApp: The Ultimate Guide (2026)

Security Notice

Moltbot on WhatsApp

The Gateway Advantage

Quick Setup (Beginner)

Minimal Config

Architecture (Who Owns What)

Getting a Phone Number

Trusted Number Sources

Why Not Twilio?

Dedicated vs. Personal Number

Dedicated Number

Personal Number

Inbound Flow (DM + Group)

DM Policy Options

Message Normalization

Group Chat Management

Group Activation Modes

Acknowledgment Reactions

Voice Notes & Media

Inbound Audio

Outbound Audio

Animated GIFs

Read Receipts

Limits & Chunking

Heartbeats & Reconnect

Full Config Reference

WhatsApp FAQ

Troubleshooting

Setting Up Moltbot with Telegram

Setting Up Moltbot with iMessage

What is Moltbot?

Moltbot vs Clawdbot: What Changed?

Setting Up Moltbot with WhatsApp: The Ultimate Guide (2026)

Security Notice

Moltbot on WhatsApp

The Gateway Advantage

Quick Setup (Beginner)

Minimal Config

Architecture (Who Owns What)

Getting a Phone Number

Trusted Number Sources

Why Not Twilio?

Dedicated vs. Personal Number

Dedicated Number

Personal Number

Login & Credentials

Inbound Flow (DM + Group)

DM Policy Options

Message Normalization

Group Chat Management

Group Activation Modes

Acknowledgment Reactions

Voice Notes & Media

Inbound Audio

Outbound Audio

Animated GIFs

Read Receipts

Limits & Chunking

Heartbeats & Reconnect

Full Config Reference

WhatsApp FAQ

Will Moltbot message random contacts when I link WhatsApp?

Can I use WhatsApp Business?

Why can't I use Twilio or a virtual number?

Does it support blue ticks (read receipts)?

Can multiple people use different Moltbots on one WhatsApp number?

Why do you ask for my phone number in the wizard?

Troubleshooting

Not linked / QR login required?

Linked but disconnected / reconnect loop?

QR Code not showing?

Disconnected frequently?

Setting Up Moltbot with Telegram

Setting Up Moltbot with iMessage

What is Moltbot?

Moltbot vs Clawdbot: What Changed?