diff --git a/apps/web/src/components/os/settings/ChannelsSettings.test.tsx b/apps/web/src/components/os/settings/ChannelsSettings.test.tsx
index cf01026..080e36d 100644
--- a/apps/web/src/components/os/settings/ChannelsSettings.test.tsx
+++ b/apps/web/src/components/os/settings/ChannelsSettings.test.tsx
@@ -165,6 +165,19 @@ describe('ChannelsSettings protected API integration', () => {
await waitFor(() => expect(mocks.setChannelRunning).toHaveBeenCalledWith('whatsapp', false));
});
+ it('warns about the unofficial WhatsApp client and shows browser setup progress', async () => {
+ mocks.getChannels.mockResolvedValue(channels.map(channel => channel.platform === 'whatsapp'
+ ? { ...channel, running: true, detail: 'Downloading a browser for WhatsApp (about 170 MB): 42%' }
+ : channel));
+ render();
+
+ const whatsapp = await screen.findByRole('region', { name: 'WhatsApp' });
+ expect(within(whatsapp).getByText(/unofficial client/)).toHaveTextContent(/may block the\s+account/);
+ expect(within(whatsapp).getByText(/unofficial client/)).toHaveTextContent(/secondary number/);
+ expect(within(whatsapp).getByRole('status')).toHaveTextContent('Downloading a browser for WhatsApp (about 170 MB): 42%');
+ expect(within(whatsapp).queryByRole('img', { name: 'WhatsApp pairing QR code' })).not.toBeInTheDocument();
+ });
+
it('shows a lifecycle failure and clears it after a successful retry', async () => {
mocks.setChannelRunning
.mockRejectedValueOnce(new Error('WhatsApp transport unavailable'))
diff --git a/apps/web/src/components/os/settings/ChannelsSettings.tsx b/apps/web/src/components/os/settings/ChannelsSettings.tsx
index 69e79de..e702445 100644
--- a/apps/web/src/components/os/settings/ChannelsSettings.tsx
+++ b/apps/web/src/components/os/settings/ChannelsSettings.tsx
@@ -5,7 +5,7 @@
* Talks to the sidecar's /api/channels surface. Security model mirrored in
* copy: deny-by-default pairing (mint a code here, DM it to the bot), bot
* tokens go straight to the vault (reads come back masked). WhatsApp shows
- * the founder-mandated ban-risk disclosure and renders Baileys' pairing QR.
+ * the ban-risk warning for the unofficial client and renders the pairing QR.
*/
import { useCallback, useEffect, useRef, useState } from 'react';
@@ -45,7 +45,7 @@ const PLATFORM_META: Record.',
+ setupHint: 'Enable and start, then scan the QR with WhatsApp → Linked Devices. From another WhatsApp account, send the linked number /pair . Messages to yourself are not read.',
},
};
@@ -63,7 +63,7 @@ function StatusBadge({ s }: { s: ChannelStatus }) {
return {label};
}
-/** Renders a Baileys pairing string as a QR image. */
+/** Renders the WhatsApp Web pairing string as a QR image. */
function WhatsAppQr({ qr }: { qr: string }) {
const [dataUrl, setDataUrl] = useState(null);
useEffect(() => {
@@ -246,14 +246,20 @@ const ChannelsSettings = () => {
{ch.platform === 'whatsapp' && (
- Heads-up: WhatsApp support uses an unofficial client (Baileys) that
- violates WhatsApp’s Terms of Service. Accounts can be banned.
- Strongly consider linking a secondary number, not your personal one.
+ Heads-up: WhatsApp support uses an unofficial client that runs
+ WhatsApp Web in a browser. WhatsApp does not allow this and may block the
+ account. Link a secondary number, not your personal one.
+ It needs Chrome, Edge or Chromium; if none is installed, Waggle downloads a browser
+ (about 170 MB) the first time you start WhatsApp.
)}
{meta.setupHint}
+ {ch.detail && ch.running && !ch.connected && (
+ {ch.detail}
+ )}
+
{ch.lastError && !ch.connected && (
Last error: {ch.lastError}
)}
@@ -264,7 +270,7 @@ const ChannelsSettings = () => {
)}
- {/* WhatsApp pairing QR (Baileys) */}
+ {/* WhatsApp pairing QR */}
{ch.platform === 'whatsapp' && ch.running && !ch.connected && ch.qr && (
)}
diff --git a/apps/web/src/lib/adapter.ts b/apps/web/src/lib/adapter.ts
index e648eec..ad406b8 100644
--- a/apps/web/src/lib/adapter.ts
+++ b/apps/web/src/lib/adapter.ts
@@ -111,6 +111,8 @@ export interface ChannelStatus {
lastActivityAt?: number;
qr?: string;
paired?: boolean;
+ /** WhatsApp: the step before the QR appears (browser lookup or download). */
+ detail?: string;
config: { enabled: boolean; defaultWorkspace: string };
secrets: Record;
}
diff --git a/docs/oss/upstream-fixes.md b/docs/oss/upstream-fixes.md
index eefa2b7..1a6a4c1 100644
--- a/docs/oss/upstream-fixes.md
+++ b/docs/oss/upstream-fixes.md
@@ -58,6 +58,7 @@ Baseline: commit `b20b138` of `git.os-dev.tech/oleg.m/waggle-os`.
| UF-027 | Self-learning loops run on data nothing collects | Open | Agent, self-learning |
| UF-028 | The Settings prompt-shape choice has no effect on chat | Open | Web UI, chat |
| UF-029 | The Settings "Import Data" button does nothing | Open | Web UI |
+| UF-030 | WhatsApp setup hint suggests pairing from the "Message yourself" chat, which is never read | Fixed | Web UI, channels |
## Entries
@@ -295,3 +296,11 @@ Entries UF-010 to UF-019 come from the UI audit `anti-slop/audit-001-2026-10-14.
- What we did: import history is hidden in the community edition v1 (decision Q2), so the button is hidden behind the memory feature map rather than wired.
- Recommendation: connect it to the existing import flow (the Memory → Imports screen) or remove it.
+### UF-030. WhatsApp setup hint suggests pairing from the "Message yourself" chat, which is never read
+- Status: Fixed
+- Found: 2026-10-24
+- Where: at commit `b20b138`, `apps/web/src/components/os/settings/ChannelsSettings.tsx:48` (`setupHint`) and `packages/server/src/local/channels/whatsapp-adapter.ts:417` (`if (!jid || raw.key.fromMe) return null`)
+- Symptom: Settings → Channels tells the user to "Message yourself or the linked number /pair ". A `/pair` sent in the "Message yourself" chat of the linked account gets no reply and pairs nothing.
+- Cause: messages the linked account sends, including those to itself, arrive with `fromMe` set, and the adapter drops every `fromMe` message (correctly, so the bot never reads its own replies).
+- What we did: the hint now says to send `/pair ` to the linked number from another WhatsApp account and that messages to yourself are not read. The `whatsapp-web.js` adapter drops own messages the same way.
+- Recommendation: change the hint in the main project the same way, or support the self-chat explicitly (accept `fromMe` messages in the account's own chat and skip the bot's replies there).