From 3784b3488dca4f9dbc9586e681aa9e28c35b6c34 Mon Sep 17 00:00:00 2001
From: Jones Fernandes <55116367+KeysiJones@users.noreply.github.com>
Date: Sun, 8 Mar 2026 10:12:22 -0300
Subject: [PATCH] docs: add WhatsApp Web Gateway setup with QR code
 instructions

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)

diff --git a/README.md b/README.md
index 746b84277..5be6b9c84 100644
--- a/README.md
+++ b/README.md
@@ -264,6 +264,97 @@ Connect your agents to every platform your users are on.
 
 Each adapter supports per-channel model overrides, DM/group policies, rate limiting, and output formatting.
 
+---
+
+## WhatsApp Web Gateway (QR Code)
+
+Connect your personal WhatsApp account to OpenFang via QR code — just like WhatsApp Web. No Meta Business account required.
+
+### Prerequisites
+
+- **Node.js >= 18** installed ([download](https://nodejs.org/))
+- OpenFang installed and initialized
+
+### Setup
+
+**1. Install the gateway dependencies:**
+
+```bash
+cd packages/whatsapp-gateway
+npm install
+```
+
+**2. Configure `config.toml`:**
+
+```toml
+[channels.whatsapp]
+mode = "web"
+default_agent = "assistant"
+```
+
+**3. Set the gateway URL (choose one):**
+
+Add to your shell profile for persistence:
+
+```bash
+# macOS / Linux
+echo 'export WHATSAPP_WEB_GATEWAY_URL="http://127.0.0.1:3009"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Or set it inline when starting the gateway:
+
+```bash
+export WHATSAPP_WEB_GATEWAY_URL="http://127.0.0.1:3009"
+```
+
+**4. Start the gateway:**
+
+```bash
+node packages/whatsapp-gateway/index.js
+```
+
+The gateway listens on port `3009` by default. Override with `WHATSAPP_GATEWAY_PORT`.
+
+**5. Start OpenFang:**
+
+```bash
+openfang start
+# Dashboard at http://localhost:4200
+```
+
+**6. Scan the QR code:**
+
+Open the dashboard → **Channels** → **WhatsApp**. A QR code will appear. Scan it with your phone:
+
+> **WhatsApp** → **Settings** → **Linked Devices** → **Link a Device**
+
+Once scanned, the status changes to `connected` and incoming messages are routed to your configured agent.
+
+### Gateway Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `WHATSAPP_WEB_GATEWAY_URL` | Gateway URL for OpenFang to connect to | _(empty = disabled)_ |
+| `WHATSAPP_GATEWAY_PORT` | Port the gateway listens on | `3009` |
+| `OPENFANG_URL` | OpenFang API URL the gateway reports to | `http://127.0.0.1:4200` |
+| `OPENFANG_DEFAULT_AGENT` | Agent that handles incoming messages | `assistant` |
+
+### Gateway API Endpoints
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| `POST` | `/login/start` | Generate QR code (returns base64 PNG) |
+| `GET` | `/login/status` | Connection status (`disconnected`, `qr_ready`, `connected`) |
+| `POST` | `/message/send` | Send a message (`{ "to": "5511999999999", "text": "Hello" }`) |
+| `GET` | `/health` | Health check |
+
+### Alternative: WhatsApp Cloud API
+
+For production workloads, use the [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api) with a Meta Business account. See the [Cloud API configuration docs](https://openfang.sh/docs/channels/whatsapp).
+
+
+
 ---
 
 ## 27 LLM Providers — 123+ Models