feat(web): warn about the unofficial WhatsApp client and show browser setup (P1.7)

The WhatsApp card in Settings > Channels now says the client is
unofficial, that WhatsApp may block the account, and that a browser is
downloaded (about 170 MB) when none is installed. While the adapter
looks for or downloads the browser, its status detail is shown above
the QR.

The setup hint told users to send /pair from the "Message yourself"
chat, which the adapter never reads because own messages are dropped.
It now says to send it from another WhatsApp account (UF-030).
This commit is contained in:
shumeiko.it
2026-10-24 11:51:32 +02:00
parent 625545aa0f
commit 6e66028a66
4 changed files with 37 additions and 7 deletions

View File

@@ -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(<ChannelsSettings />);
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'))

View File

@@ -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<ChannelPlatform, {
whatsapp: {
label: 'WhatsApp',
secretFields: [],
setupHint: 'Enable and start, then scan the QR with WhatsApp → Linked Devices. Message yourself or the linked number /pair <code>.',
setupHint: 'Enable and start, then scan the QR with WhatsApp → Linked Devices. From another WhatsApp account, send the linked number /pair <code>. Messages to yourself are not read.',
},
};
@@ -63,7 +63,7 @@ function StatusBadge({ s }: { s: ChannelStatus }) {
return <span className={`px-2 py-0.5 rounded-full text-[11px] font-display ${tone}`}>{label}</span>;
}
/** 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<string | null>(null);
useEffect(() => {
@@ -246,14 +246,20 @@ const ChannelsSettings = () => {
{ch.platform === 'whatsapp' && (
<div className="p-2.5 rounded-lg border border-destructive/40 bg-destructive/5 text-[11px] text-destructive leading-relaxed">
<strong>Heads-up:</strong> WhatsApp support uses an unofficial client (Baileys) that
violates WhatsApp&rsquo;s Terms of Service. Accounts can be <strong>banned</strong>.
Strongly consider linking a <strong>secondary number</strong>, not your personal one.
<strong>Heads-up:</strong> WhatsApp support uses an unofficial client that runs
WhatsApp Web in a browser. WhatsApp does not allow this and may <strong>block the
account</strong>. Link a <strong>secondary number</strong>, 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.
</div>
)}
<p className="text-[11px] text-muted-foreground leading-relaxed">{meta.setupHint}</p>
{ch.detail && ch.running && !ch.connected && (
<p className="text-[11px] text-muted-foreground" role="status">{ch.detail}</p>
)}
{ch.lastError && !ch.connected && (
<p className="text-[11px] text-destructive">Last error: {ch.lastError}</p>
)}
@@ -264,7 +270,7 @@ const ChannelsSettings = () => {
</p>
)}
{/* WhatsApp pairing QR (Baileys) */}
{/* WhatsApp pairing QR */}
{ch.platform === 'whatsapp' && ch.running && !ch.connected && ch.qr && (
<WhatsAppQr qr={ch.qr} />
)}

View File

@@ -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<string, string | null>;
}

View File

@@ -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 <code>". 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 <code>` 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).