Skip to content

Agent Zero AI framework

Simplify WhatsApp pairing to one QR-code action

Alessandro0e9ef3727399
diff --git a/plugins/_whatsapp_integration/AGENTS.md b/plugins/_whatsapp_integration/AGENTS.md
index f1587203a..79ed54f1d 100644
--- a/plugins/_whatsapp_integration/AGENTS.md
+++ b/plugins/_whatsapp_integration/AGENTS.md
@@ -23,10 +23,12 @@
## Work Guidance
- Coordinate Node bridge changes with Python bridge client and settings UI.
+- Pairing starts on one explicit Show QR code action, which enables the draft configuration. Keep QR polling sequential and ignore responses after cancellation or modal cleanup; saving remains owned by the settings wizard.
## Verification
- Run `node --test tests/test_whatsapp_bridge.mjs` and `pytest tests/test_whatsapp_bridge_manager.py tests/test_whatsapp_number_utils.py tests/test_whatsapp_storage_paths.py` from the repository root.
+- Run `node --test tests/test_whatsapp_config_store.mjs` for pairing lifecycle changes; verify the two-column pairing layout and its mobile stack in the WebUI.
- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical.
## Child DOX Index
diff --git a/plugins/_whatsapp_integration/README.md b/plugins/_whatsapp_integration/README.md
index 383ba853b..da6412e6e 100644
--- a/plugins/_whatsapp_integration/README.md
+++ b/plugins/_whatsapp_integration/README.md
@@ -20,10 +20,10 @@ Dependencies are auto-installed on first bridge start if missing.
### Configure and pair
-1. Enable the plugin in Settings > External > WhatsApp Integration
+1. Open Settings > External > WhatsApp Integration
2. Configure allowed phone numbers
-3. Click Show QR Code and scan with WhatsApp on your phone
-4. Send a message from an allowed number to start a chat
+3. Click Show QR code, then use WhatsApp > Linked devices > Link a device to scan it. No separate enable step is needed to show the code.
+4. Finish the setup wizard to save, then send a message from an allowed number to start a chat
5. Use `/project <name>`, `/config <preset>`, or `/send` in WhatsApp to control the active chat directly
The WhatsApp session persists across restarts in `tmp/whatsapp/session/`. No re-pairing needed unless you disconnect via settings.
diff --git a/plugins/_whatsapp_integration/webui/config.html b/plugins/_whatsapp_integration/webui/config.html
index 1cb47bb92..f4033e1cf 100644
--- a/plugins/_whatsapp_integration/webui/config.html
+++ b/plugins/_whatsapp_integration/webui/config.html
@@ -45,95 +45,48 @@
<template x-if="$store.whatsappConfig.currentStep === 0">
<div class="wa-step-panel">
- <div class="field">
- <div class="field-label">
- <div class="field-title">Turn on WhatsApp</div>
- <div class="field-description">Enable the local bridge to start.</div>
- </div>
- <div class="field-control">
- <label class="toggle">
- <input type="checkbox"
- x-model="config.enabled"
- @change="$store.whatsappConfig.onEnabledChange()" />
- <span class="toggler"></span>
- </label>
- </div>
- </div>
-
- <template x-if="config.enabled">
- <div>
- <div class="field">
- <div class="field-label">
- <div class="field-title">WhatsApp account</div>
- <div class="field-description">
- <span x-show="!$store.whatsappConfig.disconnectMessage">Click "Show QR code" to pair your WhatsApp account.</span>
- <span x-show="$store.whatsappConfig.disconnectMessage"
- x-text="$store.whatsappConfig.disconnectMessage"></span>
+ <div class="wa-pairing-row">
+ <div class="wa-qr-panel">
+ <div class="wa-qr-status">Scan to link WhatsApp</div>
+ <div class="wa-qr-content">
+ <button type="button" class="btn btn-field"
+ x-show="!$store.whatsappConfig.qrVisible"
+ @click="$store.whatsappConfig.showQr()">Show QR code</button>
+ <template x-if="$store.whatsappConfig.qrVisible">
+ <div>
+ <template x-if="$store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl">
+ <img :src="$store.whatsappConfig.qrDataUrl" alt="WhatsApp pairing QR code"
+ class="wa-qr-image" />
+ </template>
+ <div role="status" class="wa-qr-message"
+ x-show="$store.whatsappConfig.qrStatus !== 'waiting_scan'"
+ x-text="$store.whatsappConfig.qrMessage"></div>
+ <button type="button" class="btn btn-field"
+ x-show="$store.whatsappConfig.qrStatus === 'error'"
+ @click="$store.whatsappConfig.showQr()">Try again</button>
</div>
- </div>
- <div class="field-control wa-inline-actions">
- <button class="btn btn-field" @click="$store.whatsappConfig.showQr()">
- Show QR code
- </button>
- <button class="btn btn-field" @click="$store.whatsappConfig.disconnectAccount()"
- :disabled="$store.whatsappConfig.disconnecting">
- <span x-show="!$store.whatsappConfig.disconnecting">Disconnect</span>
- <span x-show="$store.whatsappConfig.disconnecting">Disconnecting...</span>
- </button>
- </div>
+ </template>
</div>
-
- <template x-if="$store.whatsappConfig.qrVisible">
- <div class="wa-qr-panel">
- <template x-if="$store.whatsappConfig.qrStatus === 'connected'">
- <div>
- <div class="wa-qr-status ok">Connected</div>
- <div class="wa-qr-message" x-text="$store.whatsappConfig.qrMessage"></div>
- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"
- style="margin-top: 12px;">
- Close
- </button>
- </div>
- </template>
-
- <template
- x-if="$store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl">
- <div>
- <div class="wa-qr-status">Scan with WhatsApp on your phone</div>
- <img :src="$store.whatsappConfig.qrDataUrl" alt="WhatsApp QR Code"
- class="wa-qr-image" />
- <div class="wa-qr-help">The QR code refreshes automatically.</div>
- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"
- style="margin-top: 12px;">
- Cancel
- </button>
- </div>
- </template>
-
- <template
- x-if="$store.whatsappConfig.qrStatus !== 'connected' && !($store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl)">
- <div>
- <div class="wa-qr-status"
- x-text="$store.whatsappConfig.qrMessage || 'Connecting...'"></div>
- <div class="wa-qr-help"
- x-show="$store.whatsappConfig.qrStatus !== 'error'">
- Please wait...</div>
- <div class="wa-qr-help error"
- x-show="$store.whatsappConfig.qrStatus === 'error'"
- x-text="$store.whatsappConfig.qrMessage"></div>
- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"
- style="margin-top: 12px;">
- Cancel
- </button>
- </div>
- </template>
- </div>
- </template>
+ <button type="button" class="btn btn-field" x-show="$store.whatsappConfig.qrVisible"
+ @click="$store.whatsappConfig.hideQr()"
+ x-text="$store.whatsappConfig.qrStatus === 'connected' ? 'Close' : 'Hide QR code'"></button>
+ </div>
+ <div class="wa-pairing-instructions">
+ <div class="wa-qr-status">Link your account</div>
+ <ol class="wa-pairing-steps">
+ <li>Click <strong>Show QR code</strong>.</li>
+ <li>Open WhatsApp on your phone and go to <strong>Settings → Linked devices</strong> (Android: <strong>⋮ → Linked devices</strong>).</li>
+ <li>Tap <strong>Link a device</strong> and scan the code.</li>
+ </ol>
+ <p class="wa-qr-help">The QR code refreshes automatically while it is open.</p>
+ <p class="wa-qr-help">Choose who can reach your agent below, then finish setup to save.</p>
+ <button type="button" class="btn btn-field" x-show="config.enabled"
+ @click="$store.whatsappConfig.disconnectAccount()"
+ :disabled="$store.whatsappConfig.disconnecting"
+ x-text="$store.whatsappConfig.disconnecting ? 'Disconnecting...' : 'Disconnect account'"></button>
+ <div role="status" class="wa-qr-help" x-show="$store.whatsappConfig.disconnectMessage"
+ x-text="$store.whatsappConfig.disconnectMessage"></div>
</div>
- </template>
-
- <div class="wa-note" x-show="!config.enabled">
- Turn on WhatsApp to pair or switch your account.
</div>
<div class="field">
@@ -200,6 +153,22 @@
<template x-if="$store.whatsappConfig.currentStep === 1">
<div class="wa-step-panel">
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Enable WhatsApp</div>
+ <div class="field-description">Receive messages from your linked account after saving.</div>
+ </div>
+ <div class="field-control">
+ <label class="toggle">
+ <input type="checkbox"
+ aria-label="Enable WhatsApp"
+ x-model="config.enabled"
+ @change="$store.whatsappConfig.onEnabledChange()" />
+ <span class="toggler"></span>
+ </label>
+ </div>
+ </div>
+
<div class="field">
<div class="field-label">
<div class="field-title">Project</div>
@@ -435,28 +404,44 @@
font-size: var(--font-size-small);
}
- .wa-inline-actions {
- display: flex;
- gap: 0.75rem;
- flex-wrap: wrap;
+ .wa-pairing-row {
+ display: grid;
+ grid-template-columns: minmax(16rem, 18rem) minmax(0, 1fr);
+ gap: 1rem;
+ align-items: stretch;
+ margin-bottom: 1rem;
}
- .wa-qr-panel {
- margin-top: 0.25rem;
+ .wa-qr-panel,
+ .wa-pairing-instructions {
padding: 1rem;
- border-radius: 14px;
- border: 1px solid color-mix(in srgb, var(--color-border) 88%, white 12%);
+ border-radius: 0.5rem;
background: color-mix(in srgb, var(--color-background) 90%, white 10%);
+ }
+
+ .wa-qr-panel {
text-align: center;
}
+ .wa-qr-content {
+ min-height: 150px;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ margin-bottom: 0.8rem;
+ overflow-wrap: anywhere;
+ }
+
.wa-qr-status {
font-weight: 700;
margin-bottom: 0.5rem;
}
- .wa-qr-status.ok {
- color: #7ee7a4;
+ .wa-pairing-steps {
+ margin: 0;
+ padding-left: 1.15rem;
+ color: var(--color-text-secondary);
+ line-height: 1.55;
}
.wa-qr-message,
@@ -467,20 +452,16 @@
.wa-qr-help {
font-size: var(--font-size-small);
- margin-top: 0.4rem;
- }
-
- .wa-qr-help.error {
- color: #fca5a5;
+ margin-top: 0.8rem;
}
.wa-qr-image {
+ display: block;
width: 256px;
- height: 256px;
+ height: auto;
max-width: 100%;
- border-radius: 8px;
+ border-radius: 0.5rem;
background: white;
- padding: 4px;
}
.wa-advanced {
@@ -595,6 +576,10 @@
}
@media (max-width: 640px) {
+ .wa-pairing-row {
+ grid-template-columns: minmax(0, 1fr);
+ }
+
.wa-summary-card,
.wa-step-header,
diff --git a/plugins/_whatsapp_integration/webui/whatsapp-config-store.js b/plugins/_whatsapp_integration/webui/whatsapp-config-store.js
index f236d4ab0..8ce0a1d2f 100644
--- a/plugins/_whatsapp_integration/webui/whatsapp-config-store.js
+++ b/plugins/_whatsapp_integration/webui/whatsapp-config-store.js
@@ -5,7 +5,7 @@ const API_BASE = "/plugins/_whatsapp_integration";
const STEPS = [
{
title: "Pair your account and set access",
- description: "Turn on WhatsApp, connect the account, and choose who can reach it.",
+ description: "Link WhatsApp with a QR code, then choose who can reach your agent.",
},
{
title: "Choose where conversations go",
@@ -44,6 +44,7 @@ export const store = createStore("whatsappConfig", {
qrMessage: "",
qrDataUrl: null,
qrPollTimer: null,
+ _qrSession: 0,
disconnecting: false,
disconnectMessage: "",
steps: STEPS,
@@ -223,44 +224,51 @@ export const store = createStore("whatsappConfig", {
},
async showQr() {
+ if (!this.config) return;
+ this.hideQr();
+ this.config.enabled = true;
+ this.disconnectMessage = "";
this.qrVisible = true;
this.qrStatus = "loading";
- this.qrMessage = "Starting the WhatsApp bridge...";
+ this.qrMessage = "Preparing QR code...";
this.qrDataUrl = null;
await this.pollQr();
- this.qrPollTimer = setInterval(() => this.pollQr(), 3000);
},
hideQr() {
+ this._qrSession += 1;
this.qrVisible = false;
this.qrDataUrl = null;
this.qrStatus = "";
if (this.qrPollTimer) {
- clearInterval(this.qrPollTimer);
+ clearTimeout(this.qrPollTimer);
this.qrPollTimer = null;
}
},
- async pollQr() {
+ async pollQr(session = this._qrSession) {
+ if (!this.qrVisible || session !== this._qrSession) return;
try {
const response = await API.callJsonApi(`${API_BASE}/qr_code`, {});
+ if (!this.qrVisible || session !== this._qrSession) return;
this.qrStatus = response.status || "error";
this.qrMessage = response.message || "";
this.qrDataUrl = response.qr || null;
-
- if (response.status === "connected" && this.qrPollTimer) {
- clearInterval(this.qrPollTimer);
- this.qrPollTimer = null;
- }
} catch (error) {
+ if (!this.qrVisible || session !== this._qrSession) return;
this.qrStatus = "error";
this.qrMessage = String(error);
this.qrDataUrl = null;
}
+ this.qrPollTimer = null;
+ if (this.qrStatus !== "connected" && this.qrStatus !== "error") {
+ this.qrPollTimer = setTimeout(() => this.pollQr(session), 3000);
+ }
},
async disconnectAccount() {
if (!window.confirm("Disconnect this WhatsApp account? You will need to scan a new QR code to reconnect.")) return;
+ this.hideQr();
this.disconnecting = true;
this.disconnectMessage = "";
try {
diff --git a/tests/test_whatsapp_config_store.mjs b/tests/test_whatsapp_config_store.mjs
new file mode 100644
index 000000000..37dc8cc1b
--- /dev/null
+++ b/tests/test_whatsapp_config_store.mjs
@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+import test from 'node:test';
+
+test('one-click pairing enables WhatsApp and polling stops on cancel, error, connection or cleanup', async () => {
+ const requests = [];
+ const timers = new Map();
+ let nextTimer = 0;
+ const source = readFileSync(new URL('../plugins/_whatsapp_integration/webui/whatsapp-config-store.js', import.meta.url), 'utf8')
+ .replace(/^import .*;\n/gm, '').replace('export const store', 'const store');
+ const store = vm.runInNewContext(`${source}\nstore`, {
+ createStore: (_name, value) => value,
+ API: { callJsonApi: () => new Promise((resolve, reject) => requests.push({ resolve, reject })) },
+ setTimeout: fn => { timers.set(++nextTimer, fn); return nextTimer; },
+ clearTimeout: id => timers.delete(id),
+ });
+ store.config = { enabled: false };
+ const initial = store.showQr();
+ assert.equal(store.config.enabled, true);
+ assert.equal(store.qrVisible, true);
+ assert.equal(requests.length, 1);
+ store.hideQr();
+ requests.shift().resolve({ status: 'waiting_scan', qr: 'stale' });
+ await initial;
+ assert.equal(store.qrDataUrl, null);
+ assert.equal(timers.size, 0);
+
+ const old = store.showQr();
+ const retry = store.showQr();
+ requests.shift().resolve({ status: 'connected' });
+ await old;
+ assert.equal(store.qrStatus, 'loading');
+ requests.shift().resolve({ status: 'waiting_scan', qr: 'current' });
+ await retry;
+ assert.equal(store.qrDataUrl, 'current');
+ assert.equal(timers.size, 1);
+ const [id, tick] = [...timers][0];
+ timers.delete(id);
+ const poll = tick();
+ requests.shift().resolve({ status: 'connected' });
+ await poll;
+ assert.equal(timers.size, 0);
+ assert.equal(store.qrStatus, 'connected');
+
+ const failed = store.showQr();
+ requests.shift().reject(new Error('Unavailable'));
+ await failed;
+ assert.equal(store.qrStatus, 'error');
+ assert.equal(timers.size, 0);
+
+ const closing = store.showQr();
+ store.cleanup();
+ requests.shift().resolve({ status: 'waiting_scan', qr: 'closed' });
+ await closing;
+ assert.equal(store.qrVisible, false);
+ assert.equal(store.qrDataUrl, null);
+ assert.equal(timers.size, 0);
+});