Files
waggle-os/docs/oss/adr/0005-whatsapp-web-js.md
shumeiko.it 625545aa0f feat(server): run the WhatsApp channel on whatsapp-web.js (P1.7)
Baileys depends on libsignal (GPL-3.0), which the sidecar bundled. The
WhatsApp adapter now drives WhatsApp Web through whatsapp-web.js and
keeps its public shape: start, stop, status with the pairing QR, send
and inbound text. LocalAuth stores the session as a browser profile in
<dataDir>/channels/whatsapp; the old Baileys state is left untouched.

The browser comes from whatsapp-browser.ts: CHROME_PATH or
PUPPETEER_EXECUTABLE_PATH, then an installed Chrome, Edge or Chromium
(Windows, macOS, Linux), then a Chrome for Testing build downloaded on
the first start into <dataDir>/browsers, with progress in the status.
The root .puppeteerrc.cjs stops npm install from downloading a browser.
The sidecar build keeps whatsapp-web.js external: bundled, it fails on
__dirname and would inline LGPL node-webpmux. Text only, so ffmpeg is
never needed.

New dependencies, pinned: whatsapp-web.js 1.34.7 (Apache-2.0) and
@puppeteer/browsers 2.13.0 (Apache-2.0). Transitive: puppeteer,
puppeteer-core, chromium-bidi, webdriver-bidi-protocol (Apache-2.0),
devtools-protocol (BSD-3-Clause), extract-zip (BSD-2-Clause),
fluent-ffmpeg and the rest (MIT or ISC), and node-webpmux
(LGPL-3.0-or-later, shipped as a separate package; needs the license
review). Removed: @whiskeysockets/baileys and libsignal.

UF-020 is now Fixed; ADR-0005 records the consequences.
2026-10-24 11:56:38 +02:00

3.9 KiB

ADR-0005: The WhatsApp channel uses whatsapp-web.js

  • Status: Accepted, one open item (browser source)
  • Date: 2026-10-14

Context

The WhatsApp channel (packages/server/src/local/channels/whatsapp-adapter.ts) uses Baileys. Baileys itself is MIT, but it depends on libsignal, which is GPL-3.0. The sidecar build bundles both, which would put GPL code into the shipped community edition.

Decision

Replace Baileys with whatsapp-web.js (Apache-2.0) and remove Baileys from the dependencies of server and launcher.

Consequences

Implemented in P1.7 with whatsapp-web.js 1.34.7 (Puppeteer 24).

  • The adapter keeps its public shape: start, stop, status with the pairing QR, send and inbound text. LocalAuth keeps the session as a browser profile in <dataDir>/channels/whatsapp/session, next to the WhatsApp Web page cache.
  • The session is no longer encrypted at rest. Baileys state lived in the encrypted vault; the browser profile is protected only by file permissions.
  • Baileys pairings are not migrated: whatsapp-web.js cannot use them. The old vault entry and <dataDir>/channels/whatsapp-auth are left untouched because the data directory may still be shared with the commercial edition. Users scan the QR once more.
  • Installing dependencies does not download a browser: the root .puppeteerrc.cjs sets skipDownload. This covers npm install and npm ci in this repository (development, install.sh, Tauri staging). It does not cover npx @waggle-ai/waggle: there npm runs Puppeteer's install script with no config in reach, and it downloads Chrome unless PUPPETEER_SKIP_DOWNLOAD=1 is set.
  • Open item, implemented as proposed and still awaiting the owner: the browser source. The order is CHROME_PATH or PUPPETEER_EXECUTABLE_PATH, an installed Chrome, Edge or Chromium in the standard Windows, macOS and Linux locations, then a browser downloaded earlier. Only when none is found does starting WhatsApp download the current stable Chrome for Testing (about 170 MB) into <dataDir>/browsers with @puppeteer/browsers. Settings shows the progress, or an error that asks the user to install Chrome or set CHROME_PATH. Linux on ARM has no Chrome for Testing build, so users there install Chromium.
  • The Tauri sidecar build keeps whatsapp-web.js and @puppeteer/browsers external. Bundled into the ESM sidecar, whatsapp-web.js fails at runtime (__dirname is not defined).
  • The channel handles text only. whatsapp-web.js needs ffmpeg only to turn videos into stickers, which Waggle never sends, so ffmpeg is not bundled, downloaded or looked up. Voice, video and other media messages are ignored and logged.
  • New licenses: Apache-2.0 (whatsapp-web.js, puppeteer, puppeteer-core, @puppeteer/browsers, chromium-bidi, webdriver-bidi-protocol), BSD (devtools-protocol, extract-zip), MIT and ISC for the rest, and LGPL-3.0-or-later for node-webpmux, a required dependency of whatsapp-web.js that it loads on startup for sticker metadata. It ships as a separate, unmodified package. The licensing review has to accept it.
  • The client is unofficial. Settings warns that WhatsApp may block the account and recommends a secondary number.
  • Risk: whatsapp-web.js awaits page work inside browser event listeners (for example inject() after a navigation, which throws "auth timeout" when WhatsApp Web loads slowly). Such a failure is an unhandled promise rejection, and the sidecar has no handler for those, so Node stops the process.

Alternatives considered

  • whatsmeow (Go, MPL-2.0): no browser, but needs a separate Go binary per platform.
  • WPPConnect (LGPL-3.0): also browser-based, stricter license.
  • venom-bot: no npm release since November 2024.
  • open-wa: Hippocratic license, not an open-source license in the OSI sense.
  • WhatsApp Business Cloud API: needs a business account and a public webhook, so it does not fit a local app.