WhatsAppGo

WhatsAppGo is an unofficial, native WhatsApp client for Linux. Its interface is built with Qt 6 and QML. A bundled Go backend uses whatsmeow to connect through WhatsApp's multi-device protocol. There is no Chromium, WebKit, Electron, or WhatsApp Web page in the application.

The desktop application starts and owns its backend automatically. Build it, launch whatsappgo, and use it as one application—there is no service or systemd unit to start manually.

Important: WhatsAppGo is not affiliated with, authorized by, or endorsed by WhatsApp or Meta. Voice and video calls cannot be placed because the underlying protocol library does not implement them, and protocol changes can interrupt the rest at any time.

Your account is at risk. WhatsApp's Terms of Service permit only its own applications. Connecting with a client built on a reverse-engineered protocol breaches those terms, whatever you use it for, and WhatsApp may ban the number rather than the software: the account is what it can reach. Automated or high-volume sending, unsolicited messages, scraping, bulk or repeated contact with people who have not asked to hear from you, and operating many accounts from one place are what actually get numbers banned, and the bot API here makes all of them easy to do by accident. A ban can take the phone number with it, including the account you use with WhatsApp's own app.

Use it with a number you can afford to lose, for conversations you are a part of. There is no appeal process this project can offer you and no way to undo a ban from here.

Quick start

Download for Linux

Every tagged version publishes an AppImage: one file, no build tools. Put it somewhere you can write to, because an update installs itself by replacing that file.

mkdir -p ~/Applications && cd ~/Applications
curl -LO https://github.com/shukiv/whatsappgo/releases/latest/download/WhatsAppGo-x86_64.AppImage
curl -LO https://github.com/shukiv/whatsappgo/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
chmod +x WhatsAppGo-x86_64.AppImage
./WhatsAppGo-x86_64.AppImage

The checksum line has to print WhatsAppGo-x86_64.AppImage: OK before the file is worth running. On a system without FUSE, start it with ./WhatsAppGo-x86_64.AppImage --appimage-extract-and-run.

The published binaries are unsigned: the checksum confirms that the download arrived intact, not who built it. Building from source avoids the question.

Build from source

On Debian 13:

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build pkg-config \
  qt6-base-dev qt6-declarative-dev qt6-multimedia-dev \
  qml6-module-org-kde-desktop qt6-gtk-platformtheme \
  qml6-module-qtquick-controls qml6-module-qtmultimedia

git clone https://github.com/shukiv/whatsappgo.git
cd whatsappgo
make desktop
./desktop/build/whatsappgo

make desktop builds the Go backend, builds the Qt application, and places the backend beside the desktop executable. Starting the desktop executable starts the backend automatically. On desktops with a system tray, closing the window keeps WhatsAppGo connected in the tray; choose Quit WhatsAppGo from its tray menu to stop the application and every backend process that it owns.

To link an account, open WhatsApp on the phone and choose Settings → Linked devices → Link a device, then scan the QR code. Phone-code pairing accepts an international number without +, spaces, or a leading zero.

For Fedora, Arch, per-user installation, system-wide installation, upgrades, and uninstalling, see Installing WhatsAppGo.

Features

• QR and phone-code account linking
• multiple isolated account profiles with top-level account tabs
• text and media messages, voice notes, documents, replies, reactions, edits, delete-for-everyone, receipts, and typing indicators
• write a message now and send it later: pick a moment, see what a conversation still owes, and take any of it back before it goes (the app has to be running at that moment; a message whose time passed goes out at the next start)
• SQLite-backed history with 50-message pagination and message search
• day separators through a conversation, and Up on an empty composer edits the last message you sent
• one-click updates: a packaged build finds a new release, verifies it against the checksums the release publishes, and installs it over itself
• phone-number/LID identity consolidation so one contact has one history
• inline photo, video, and sticker previews before the full file is fetched
• voice notes with the sender's waveform that play in place and run on to the next
• built-in audio and video playback; no browser or external player
• link previews with title, description, and picture; a one-time YouTube metadata backfill repairs historical cards that arrived without thumbnails
• shared contacts and places as cards, with a phone number to message and a map
• attachments fetched automatically for the conversation on screen
• attachments stored in a database, so clearing the media cache loses nothing
• image copy/paste, native media preview, downloads, and cached avatars
• an in-app aspect-fit image viewer with zoom, copy, and save actions; media playback marks supported audio and video as played
• a WhatsApp-style contact information drawer with phone/avatar details, synchronized mute/archive controls, shared-content counts, and separate Media, Documents, and Links views backed by SQLite history
• chat filters, pinned and favorite conversations, groups, statuses, channels, communities, synchronized call records, and profile/settings screens
• followed channels open onto their posts in the conversation view, and communities you belong to through one of their groups are listed too
• group member management and permission-aware group name/description editing, with explicit Save, copyable details, and draft retention on errors
• a compact desktop shell measured against the installed WhatsApp Web PWA, including 64 px navigation/header geometry, responsive filter overflow, and menus that reposition inside the window instead of being clipped
• native system notifications with sender avatars and message sounds, independent of the tray; minimize-to-tray with late GNOME AppIndicator discovery, light/dark/system appearance, RTL text, selectable message text, clickable links, and accessible controls
• whatsappctl command-line automation with JSON output, live event streams, media sending, contact resolution, and a discoverable local API for bots
• An AI assistant interface: whatsappmcp serves the same local API over the Model Context Protocol, so an assistant can read and act on the account through the tools the daemon already publishes
• Flatpak, Debian, RPM, and AppImage packaging definitions
• Report a problem opens the WhatsAppGo GitHub issues page directly in your browser, with no in-app form or intake key; see bug reporting

Call records may be displayed when WhatsApp supplies them, but starting voice or video calls is not supported.

Documentation

• v0.1.9 release notes: the reliability fixes in this tag and their validation, distinct from published release artifacts
• Installation guide: dependencies, source build, per-user and system-wide installation, updates, and uninstalling
• User guide: pairing, accounts, messaging, history, appearance, data, and limitations
• Troubleshooting: build, startup, graphics, history, pairing, and media problems
• Development guide: repository setup, testing, debugging, packaging, and contribution workflow
• Architecture: process lifecycle, storage, event flow, identity aliases, memory behavior, and RPC
• Command-line and bot API: whatsappctl, the whatsappmcp Model Context Protocol server, events, raw methods, security, and automation examples
• Security and privacy: local plaintext data, credentials, exported profiles, reporting, and account risk
• WhatsApp Web PWA control inventory: traversed controls, menus, state branches, and measured reference geometry
• WhatsApp Web PWA gap audit: implemented parity work, remaining functionality gaps, priorities, and acceptance criteria

Requirements

• Go 1.26 or newer; an older Go installation with GOTOOLCHAIN=auto can fetch the required toolchain
• CMake 3.22 or newer and a C++20 compiler
• Qt 6.5 or newer: Core, Gui, Widgets, Quick, Quick Controls 2, Network, and Multimedia

Check native dependencies without changing the system:

make check-desktop-deps

Build, test, and install

make desktop
make test
go vet ./...
ctest --test-dir desktop/build --output-on-failure

Install under the configured CMake prefix:

cmake -S desktop -B desktop/build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
make desktop
sudo cmake --install desktop/build

whatsappgo, its internal whatsappd helper, and the optional whatsappctl automation client are installed together. Launch whatsappgo first; the CLI controls the backend that the desktop owns.

The package definitions under packaging/ build the release artifacts: an AppImage for Linux, an installer and a ZIP for Windows, and a macOS disk image. They are unsigned, and the AppImage is the one described in the quick start above; INSTALL.md covers the rest.

Qt Quick's software renderer is the default because it is reliable and light on hybrid-GPU Linux systems. A working GPU stack can opt in with:

QT_QUICK_BACKEND=rhi ./desktop/build/whatsappgo

Local data

Each account has isolated state:

Data	Default account	Additional account
Device keys/session	$XDG_DATA_HOME/whatsappgo/device.db	$XDG_DATA_HOME/whatsappgo/profiles/<name>/device.db
Chats/messages	$XDG_DATA_HOME/whatsappgo/messages.db	$XDG_DATA_HOME/whatsappgo/profiles/<name>/messages.db
Attachments	$XDG_DATA_HOME/whatsappgo/media.db	$XDG_DATA_HOME/whatsappgo/profiles/<name>/media.db
Media cache	$XDG_CACHE_HOME/whatsappgo/media/	$XDG_CACHE_HOME/whatsappgo/profiles/<name>/media/
Runtime socket	$XDG_RUNTIME_DIR/whatsappgo/whatsappd.sock	$XDG_RUNTIME_DIR/whatsappgo/whatsappd-<name>.sock

If XDG_DATA_HOME or XDG_CACHE_HOME is unset, the usual ~/.local/share and ~/.cache locations are used. messages.db stores every message delivered to this linked device. The UI reads the newest 50 messages and requests older pages while scrolling upward.

The databases contain decrypted message text and metadata. They have per-user Unix permissions but no additional application-level encryption.

Uninstall

The app removes itself, because it is the thing that knows where all of that went:

./WhatsAppGo-x86_64.AppImage --uninstall

It lists every directory and file it is about to remove with its size, and waits for you to type yes. Close the app first: its background service holds the databases, and quitting writes the settings back afterwards.

Flag	What it does
--uninstall	Lists what will go, asks, then removes it
--uninstall --yes	Skips the question, for scripts
--uninstall --keep-accounts	Removes settings, cache and the launcher entry; leaves the accounts and their message history

What goes: the accounts and their message history, the media cache, the settings, the runtime sockets, and the launcher entry an integrated AppImage leaves in ~/.local/share/applications. The AppImage itself is left where it is - delete that file yourself. On Windows, use the normal Add or remove programs entry for the app, and this flag for the data.

Your messages live only on this computer, so removing them cannot be undone. Deleting them also tells WhatsApp nothing: your phone goes on listing this computer under Settings, Linked devices until you remove it there.

Project layout

cmd/whatsappd/       internal Go backend executable
cmd/whatsappctl/     JSON command-line and bot client
cmd/whatsappmcp/     Model Context Protocol server for AI assistants
internal/whatsapp/  whatsmeow adapter and event handling
internal/store/     SQLite message index and migrations
internal/mediastore/ SQLite attachment storage
internal/rpc/       local JSON-lines RPC transport
internal/service/   application operations exposed to the desktop
desktop/            Qt application and UI tests
packaging/          Flatpak, Debian, RPM, AppImage, desktop metadata
docs/               user, developer, architecture, security, troubleshooting

License

GNU General Public License v3.0 or later. See LICENSE. Product names and trademarks belong to their respective owners.