ZapZap – WhatsApp Desktop for Linux & Windows

📌 About

ZapZap brings the WhatsApp experience on Linux closer to that of a native application.
Since Meta does not provide a public API for third-party applications, ZapZap is developed as a Progressive Web Application (PWA), built with PyQt6 + PyQt6-WebEngine.

📌 Technical documentation:
See docs/technical-documentation.md

---

📥 Download

• Flathub
• AppImage

---

✨ Features

ZapZap extends WhatsApp Web with additional features:

🎨 Appearance

• Adaptive light and dark mode
• Fullscreen mode
• Custom window decorations
• Interface scaling adjustment (ideal for 2K/4K screens)

⚡ Usability

• Keyboard shortcuts for main options
• Adaptive system tray icon (notifies new messages)
• Background process support
• Drag-and-drop functionality
• Account Grid View (Quickly switch between all accounts)
• Ability to select a custom folder for downloads
• Temporary folder for opening files

🛠️ Extras

• Spellchecker with language selection via context menu
• Customizable system tray icons
• Option to choose a folder for custom dictionaries
• Setting to disable the native file selection dialog (Hyprland)
• Custom CSS/JS with global + per-account override
• Reorganized Settings Panel
• Added Performance section
• Native Windows support (SQLite + Registry settings)

🧩 Customizations

• New Customizations page in Settings
• Supports Global customization and Current account customization
• Account mode supports inherit global settings + optional override
• Users can:
  • import .css and .js files
  • create and edit CSS/JavaScript files in dialogs
  • enable/disable each imported CSS/JS file independently
  • import CSS/JavaScript from any https:// URL
  • open customization folders directly
• Supports many userstyle files (.user.css) by extracting WhatsApp-targeted @-moz-document blocks
• Page actions: Save, Save and reload, Reload

Customization files are stored in the app local data path under:

• customizations/global/css
• customizations/global/js
• customizations/accounts/<id>/css
• customizations/accounts/<id>/js

Reserved for future extension support:

• customizations/extensions

---

⚠️ File upload notice

File uploads and filesystem permissions

To enable file uploads (documents, images, videos, audio, etc.) in WhatsApp Web, ZapZap requires access to the user’s folders.

This is due to technical limitations of QtWebEngine (Chromium) in modern environments such as Wayland and sandboxed applications (for example, Flatpak).
Under these conditions, the embedded browser cannot upload files correctly without direct access to the filesystem.

What this means in practice

• Without filesystem access:
  • file uploads may fail
  • files may be sent with no content
• With the required permissions granted:
  • file uploads work correctly
  • the experience matches that of a regular web browser

Recommended permissions

When running in a sandboxed environment (such as Flatpak), it is recommended to grant access to at least:

• Documents
• Videos
• Pictures
• Downloads

These permissions are used only to allow the user to select and upload files and are not used for automatic file scanning, indexing, or data collection.

Changing permissions on Flatpak

If ZapZap was installed via Flatpak, you can manage filesystem permissions using Flatseal (a graphical permission manager for Flatpak apps):

👉 https://flathub.org/apps/com.github.tchx84.Flatseal

Steps:

1. Install and open Flatseal
2. Select ZapZap from the application list
3. Enable access to the recommended folders (Documents, Videos, Pictures, Downloads)
4. Restart ZapZap

Optional terminal alternative:

bashCopy
flatpak override --user --filesystem=home com.rtosta.zapzap

After adjusting these permissions, file uploads, opening PDFs, and drag-and-drop should work normally.

⚙️ Development

Requirements

• Python 3.8 or higher
• pip
• System libraries required by Qt WebEngine and optionally dbus-python on Linux

Fedora 43 System Dependencies

If pip install -r requirements.txt fails due to dbus-python:

bashCopy
sudo dnf install -y dbus-devel pkg-config gcc python3-devel

Then:

bashCopy
pip install -r requirements.txt

🚀 Development Mode

bashCopy
python run.py

Debugging WebEngine

• Open DevTools for current account page: View -> Open DevTools (Ctrl+Shift+I)

🏗️ Builders

ZapZap possui builders dedicados para cada alvo de distribuição, organizados em builders/:

• builders/flatpak_builder.py: pipeline de build e empacotamento Flatpak.
• builders/appimage_builder.py: geração do artefato AppImage.
• builders/windows_builder.py: build para Windows (EXE/ZIP).

Esses builders são acionados manualmente e independente do run.py, mantendo um fluxo único de automação local e release.

📦 Build AppImage

bashCopy
python builders/appimage_builder.py --appimage <version>

Example:

bashCopy
python builders/appimage_builder.py build --appimage 6.5

📦 Build Flatpak Onefile

bashCopy
python builders/flatpak_builder.py

Output:

dist/com.rtosta.zapzap.flatpak

📦 Build Windows (EXE)

bashCopy
python builders/windows_builder.py

Output:

dist/ZapZap.exe
dist/ZapZap-Windows.zip

📦 Install as Python Module

bashCopy
pip install .

Uninstall

bashCopy
pip uninstall zapzap

🔧 uv Tool

bashCopy
uv tool install . --with-requirements requirements.txt

📦 Packaging

• Flatpak
• AppImage

🌍 Translation

ZapZap supports translations. If your language file is missing from the po folder, submit a pull request or open an issue.

🤝 Contributions

Contributions are welcome!
Please submit a pull request with any improvements or changes you wish to propose.

📜 License

This project is licensed under the GPL.
See the LICENSE file for more information.

💖 Donations

PayPal: Donate via PayPal

Pix: Donate via Pix

Ko-fi: Donate via Ko-fi

📬 Contact

Maintainer: Rafael Tosta

Email: rafa.ecomp@gmail.com