WhatsApp Automation

Desktop WhatsApp Web automation for CSV-driven message campaigns.

The application is packaged for non-technical users. They install it, open it, choose a contacts CSV and message template, scan WhatsApp Web once, and future launches reuse the saved local browser profile automatically.

The project uses Electron plus Electron Builder for distribution.

Why Electron:

• It creates a real desktop app with native installers, shortcuts, uninstall support, app metadata, and a friendly first-run experience.
• It lets the existing Node.js automation engine run unchanged in the main process.
• It supports macOS Intel, macOS Apple Silicon, and Windows from one packaging configuration.
• It is more maintainable for this use case than pkg, nexe, or Node SEA. Those tools are better for terminal executables and do not provide a professional desktop shell or installer experience by themselves.

The automation logic remains in src/core and src/infrastructure. The desktop layer in src/desktop is only an adapter.

Mutable data is stored in the operating system app-data directory, never beside the executable.

macOS:

~/Library/Application Support/WhatsApp Automation/

Windows:

%APPDATA%/WhatsApp Automation/

The app creates:

• profile/ for the persistent WhatsApp Web browser profile
• browsers/ for Playwright-managed Chromium
• logs/ for audit and diagnostic logs
• screenshots/ for failure screenshots
• state.json for resume checkpoints
• config.json for user-local runtime configuration

The app uses playwright-core and automatically installs Chromium on first launch when missing. The browser download runs silently from the desktop app and writes into the app-data browsers/ folder.

Users never need to install Node.js, npm, Playwright, Chromium, VS Code, or Git.

npm install
npm test
npm run start

The original CLI adapter is still available for development:

npm run start:cli -- --csv data/input/contacts.csv --template data/input/template.txt

npm run build
npm run package
npm run dist
npm run dist:mac
npm run dist:win

• npm run build runs tests and verifies packaging metadata.
• npm run package creates an unpacked app in release/ for inspection.
• npm run dist creates an installer for the current OS.
• npm run dist:mac creates signed-ready macOS DMG builds for Intel and Apple Silicon. Run this on macOS.
• npm run dist:win creates a Windows NSIS installer. Run this on Windows.

macOS builds produce a DMG with a standard app-to-Applications layout.

Windows builds produce an NSIS installer that:

• creates a Start Menu entry
• creates a desktop shortcut
• supports uninstall
• preserves app data during uninstall unless the release policy changes

1. Update version in package.json.
2. Run npm install if dependencies changed.
3. Run npm run build.
4. On macOS, run npm run dist:mac.
5. On Windows, run npm run dist:win.
6. Smoke-test first launch, browser download, QR scan, campaign run, restart profile reuse, and uninstall.
7. Publish the generated installer files from release/.

The macOS configuration is signing-ready and uses hardened runtime entitlements. Add Apple Developer credentials in the release environment before public distribution.

Windows signing can be added through Electron Builder certificate environment variables in the release environment.

1. Update playwright-core in package.json.
2. Run npm install.
3. Run npm test.
4. Delete the local app-data browsers/ folder on a test machine.
5. Launch the desktop app and confirm Chromium installs automatically.
6. Run a small campaign against test data.

If the app says browser resources are installing, wait for the first-launch download to finish. This can take a few minutes on slower networks.

If WhatsApp asks for a QR code, scan it in the browser window that opens. The app stores the session in the local profile/ folder and reuses it on later launches.

If a campaign stops, open the logs folder from the app and review logs.csv, combined.log, and any screenshots.

If resume is enabled, the app resumes only when the same CSV and template match the saved checkpoint.

build/                         Installer resources and signing entitlements
data/                          Development-only sample input and temporary files
docs/                          Release and product documentation
release/                       Generated installers and packaged apps
scripts/                       Build verification scripts
src/cli/                       Original command-line adapter
src/core/                      Campaign orchestration engine
src/desktop/                   Electron main process, preload bridge, and desktop UI
src/infrastructure/            Browser, IO, runtime paths, and utility adapters
tests/                         Unit and integration tests