clawdbot/docs/whatsapp.md

summary, read_when

summary	read_when
WhatsApp (web provider) integration: login, inbox, replies, media, and ops	Working on WhatsApp/web provider behavior or inbox routing

WhatsApp (web provider)

Updated: 2026-01-06

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

What it is

• WhatsApp Web connection managed by the Gateway.
• Deterministic routing: replies always return to WhatsApp.
• DMs share the agent's main session; groups are isolated (whatsapp:group:<jid>).

Setup (fast path)

1. Use a real mobile number (WhatsApp blocks most VoIP numbers).
2. Run clawdbot login and scan the QR (Linked Devices).
3. Start the gateway; the WhatsApp provider starts when a linked session exists.
4. Lock down DMs and groups (pairing + allowlists are default-safe).

Multi-account:

• clawdbot login --account <id>
• Configure whatsapp.accounts.<id> for per-account settings.

Access control (DMs + groups)

DMs:

• Default: whatsapp.dmPolicy = "pairing".
• Unknown senders get a pairing code and are ignored until approved.
• Approve via:
  • clawdbot pairing list --provider whatsapp
  • clawdbot pairing approve --provider whatsapp <CODE>
• Pairing is the default token exchange for WhatsApp DMs. Details: https://docs.clawd.bot/pairing

Groups:

• whatsapp.groupPolicy = open | allowlist | disabled.
• whatsapp.groups sets per-group defaults and becomes an allowlist when present (use "*" to allow all).
• Mention gating defaults to requireMention: true unless overridden.

How it works (behavior)

• Inbound messages are normalized into the shared provider envelope with reply context.
• Group replies require a mention by default (native mentions or routing.groupChat.mentionPatterns).
• Recent group history can be injected for context (see routing.groupChat.historyLimit).

Reply delivery

• Standard WhatsApp messages (no threaded replies).
• Text chunking is applied to stay within limits.

Media

• Images/video/audio/documents supported.
• Default cap: 5 MB per item (override via agent.mediaMaxMb).
• Oversize media returns a warning instead of sending.

Delivery targets (CLI/cron)

• DMs: E.164 (+15551234567).
• Groups: group JID (12345-678@g.us).

Configuration reference (WhatsApp)

Full configuration: https://docs.clawd.bot/configuration

Provider options:

• whatsapp.dmPolicy: pairing | allowlist | open | disabled (default: pairing).
• whatsapp.allowFrom: DM allowlist (E.164). open requires "*".
• whatsapp.groupPolicy: open | allowlist | disabled (default: open).
• whatsapp.groupAllowFrom: group sender allowlist (E.164).
• whatsapp.groups: per-group defaults + allowlist (use "*" for global defaults).
• whatsapp.textChunkLimit: outbound chunk size (chars).
• whatsapp.accounts: per-account overrides:
  • whatsapp.accounts.<id>.enabled
  • whatsapp.accounts.<id>.authDir
  • whatsapp.accounts.<id>.dmPolicy
  • whatsapp.accounts.<id>.allowFrom
  • whatsapp.accounts.<id>.groupPolicy
  • whatsapp.accounts.<id>.groupAllowFrom
  • whatsapp.accounts.<id>.groups
  • whatsapp.accounts.<id>.textChunkLimit

Runtime options (WhatsApp web provider):

• web.enabled: enable/disable provider startup.
• web.heartbeatSeconds: gateway heartbeat cadence.
• web.reconnect.*: reconnect backoff (initialMs, maxMs, factor, jitter, maxAttempts).

Related global options:

• routing.groupChat.mentionPatterns, routing.groupChat.historyLimit.
• commands.text, commands.useAccessGroups.
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope.