From a5cb51282c5cabb0948a3c84636c2965271bee02 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Fri, 9 Jan 2026 00:19:44 +0100
Subject: [PATCH] docs: clarify WhatsApp number modes

---
 docs/providers/whatsapp.md | 66 +++++++++++++++++++++++++-------------
 1 file changed, 43 insertions(+), 23 deletions(-)

diff --git a/docs/providers/whatsapp.md b/docs/providers/whatsapp.md
index 64b877e0b..cec349d88 100644
--- a/docs/providers/whatsapp.md
+++ b/docs/providers/whatsapp.md
@@ -5,7 +5,7 @@ read_when:
 ---
 # WhatsApp (web provider)
 
-Updated: 2026-01-07
+Updated: 2026-01-08
 
 Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 
@@ -19,11 +19,47 @@ Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 - **CLI / macOS app** talk to the gateway; no direct Baileys use.
 - **Active listener** is required for outbound sends; otherwise send fails fast.
 
-## Getting a phone number
+## Getting a phone number (two modes)
 
-WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked.
+WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked. There are two supported ways to run Clawdbot on WhatsApp:
 
-**Recommended approaches:**
+### 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. Great for keeping your personal WhatsApp separate — install WhatsApp Business and register the Clawdbot number there.
+
+**Sample config (dedicated number, single-user allowlist):**
+```json
+{
+  "whatsapp": {
+    "dmPolicy": "allowlist",
+    "allowFrom": ["+15551234567"]
+  }
+}
+```
+
+**Pairing mode (optional):**
+If you want pairing instead of allowlist, set `whatsapp.dmPolicy` to `pairing`. Unknown senders get a pairing code; approve with:
+`clawdbot pairing approve --provider whatsapp <code>`
+
+### Personal number (fallback)
+Quick fallback: run Clawdbot on **your own number**. Message yourself (WhatsApp “Message yourself”) for testing so you don’t spam contacts. Expect to read verification codes on your main phone during setup and experiments. **Must enable self-chat mode.**
+
+**Sample config (personal number, self-chat):**
+```json
+{
+  "whatsapp": {
+    "selfChatMode": true,
+    "dmPolicy": "allowlist",
+    "allowFrom": ["+15551234567"]
+  },
+  "messages": {
+    "responsePrefix": "[clawdbot]"
+  }
+}
+```
+
+### Number sourcing tips
 - **Local eSIM** from your country's mobile carrier (most reliable)
   - Austria: [hot.at](https://www.hot.at)
   - UK: [giffgaff](https://www.giffgaff.com) — free SIM, no contract
@@ -33,8 +69,6 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
 
 **Tip:** The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via `creds.json`.
 
-**WhatsApp Business:** You can use WhatsApp Business on the same phone with a different number. This is a great option if you want to keep your personal WhatsApp separate — just install WhatsApp Business and register it with Clawdbot's dedicated number.
-
 ## Why Not Twilio?
 - Early Clawdbot builds supported Twilio’s WhatsApp Business integration.
 - WhatsApp Business numbers are a poor fit for a personal assistant.
@@ -62,27 +96,13 @@ WhatsApp requires a real mobile number for verification. VoIP and virtual number
   - Open: requires `whatsapp.allowFrom` to include `"*"`.
   - Self messages are always allowed; “self-chat mode” still requires `whatsapp.allowFrom` to include your own number.
 
-### Same-phone mode (personal number)
-If you run Clawdbot on your **personal WhatsApp number**, set:
-
-```json
-{
-  "whatsapp": {
-    "selfChatMode": true
-  }
-}
-```
+### Personal-number mode (fallback)
+If you run Clawdbot on your **personal WhatsApp number**, enable `whatsapp.selfChatMode` (see sample above).
 
 Behavior:
 - Suppresses pairing replies for **outbound DMs** (prevents spamming contacts).
 - Inbound unknown senders still follow `whatsapp.dmPolicy`.
-
-Recommended for personal numbers:
-- Set `whatsapp.dmPolicy="allowlist"` and add your number to `whatsapp.allowFrom`.
-- Set `messages.responsePrefix` (for example, `[clawdbot]`) so replies are clearly labeled.
-- **Group policy**: `whatsapp.groupPolicy` controls group handling (`open|disabled|allowlist`).
-  - `allowlist` uses `whatsapp.groupAllowFrom` (fallback: explicit `whatsapp.allowFrom`).
-- **Self-chat mode**: avoids auto read receipts and ignores mention JIDs.
+- Self-chat mode avoids auto read receipts and ignores mention JIDs.
 - Read receipts sent for non-self-chat DMs.
 
 ## Message normalization (what the model sees)