88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
---
|
|
summary: "WhatsApp (web provider) integration: login, inbox, replies, media, and ops"
|
|
read_when:
|
|
- 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`.
|