docs: explain multi-agent WhatsApp DM routing

docs/concepts/multi-agent.md

@@ -70,6 +70,37 @@ With **multiple agents**, each `agentId` becomes a **fully isolated persona**:
 
 This lets **multiple people** share one Gateway server while keeping their AI “brains” and data isolated.
 
+## One WhatsApp number, multiple people (DM split)
+
+You can route **different WhatsApp DMs** to different agents while staying on **one WhatsApp account**. Replies still come from the same WhatsApp number (no per‑agent sender identity).
+
+Important detail: direct chats collapse to the agent’s **main session key**, so true isolation requires **one agent per person**.
+
+Example:
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "alex", workspace: "~/clawd-alex" },
+      { id: "mia", workspace: "~/clawd-mia" }
+    ]
+  },
+  bindings: [
+    { agentId: "alex", match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
+    { agentId: "mia",  match: { provider: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } }
+  ],
+  whatsapp: {
+    dmPolicy: "allowlist",
+    allowFrom: ["+15551230001", "+15551230002"]
+  }
+}
+```
+
+Notes:
+- DM access control is **global per WhatsApp account** (pairing/allowlist), not per agent.
+- For shared groups, bind the group to one agent or use [Broadcast groups](/broadcast-groups).
+
 ## Routing rules (how messages pick an agent)
 
 Bindings are **deterministic** and **most-specific wins**:

docs/providers/whatsapp.md

@@ -135,6 +135,9 @@ Pairing is a DM gate for unknown senders:
 - Approve with: `clawdbot pairing approve whatsapp <code>` (list with `clawdbot pairing list whatsapp`).
 - Codes expire after 1 hour; pending requests are capped at 3 per provider.
 
+**Can multiple people use different Clawdbots on one WhatsApp number?**  
+Yes, by routing each sender to a different agent via `bindings`. Replies still come from the **same WhatsApp account**, and direct chats collapse to each agent’s main session, so use **one agent per person**. DM access control (`dmPolicy`/`allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent).
+
 **Why do you ask for my phone number in the wizard?**  
 The wizard uses it to set your **allowlist/owner** so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that same number and enable `whatsapp.selfChatMode`.
 

docs/start/faq.md

@@ -112,6 +112,10 @@ Clawdbot supports **OpenAI Code (Codex)** via OAuth or by reusing your Codex CLI
 
 Bun is supported for faster TypeScript execution, but **WhatsApp requires Node** in this ecosystem. The wizard lets you pick the runtime; choose **Node** if you use WhatsApp.
 
+### Can multiple people use one WhatsApp number with different Clawdbots?
+
+Yes, via **multi‑agent routing**. Bind each sender’s WhatsApp DM to a different `agentId`, so each person gets their own workspace and session store. Replies still come from the **same WhatsApp account**, and DM access control (`whatsapp.dmPolicy` / `whatsapp.allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent) and [WhatsApp](/providers/whatsapp).
+
 ### Does Homebrew work on Linux?
 
 Yes. Homebrew supports Linux (Linuxbrew). Quick setup: