Skip to content

Releases

v0.6.0: an app can run the bridge, and the bridge refuses mass messaging

Choose a tag to compare

@adelaidasofia adelaidasofia released this 31 Oct 14:47
a5c6d84

An app can now run this bridge for you, the bridge refuses mass messaging, each workspace can see only its own chats, and voice-note transcription turns on in one step.

Sending: the bridge never sends mass messages. confirm_send refuses, with a reason your assistant can relay:

  • broadcast lists, status and channels;
  • a first message (or a reaction) to someone you have no conversation with yet;
  • the same text of 20+ characters to a second chat within 24 hours;
  • more than WHATSAPP_DAILY_SEND_LIMIT messages a day (default 10; 0 turns sending off). A group counts like any chat; your own "message yourself" chat is exempt.

A refused send comes with a wa.me link that opens the chat with the text filled in, so you can send it yourself. If you send more than 10 a day through the bridge today, raise WHATSAPP_DAILY_SEND_LIMIT or send by hand. Drafting is never limited.

One MCP server per workspace. WHATSAPP_CHAT_SCOPE_FILE points a server at an allow or deny list of chats, and that server lists, reads, searches and sends only within them, under every JID a person has (GET /api/aliases). WHATSAPP_API_TOKEN makes the bridge's API require a bearer token, so other accounts on the computer, sandboxed apps and web pages cannot reach the bridge around those servers. It is not a sandbox: a program running as you can still read the token. Both are off unless set.

Voice notes. python3 whatsapp-mcp-server/enable_transcription.py turns transcription on in one safe order (it looks first and changes nothing without --yes), and is a clean check on a bridge that is already set up. The language now defaults to auto. Transcripts are scrubbed for prompt injection wherever they leave the bridge. New default: WHATSAPP_KEEP_VOICE_AUDIO=true saves voice-note audio under WHATSAPP_MEDIA_PATH while transcription is off, so turning it on later reaches notes older than WhatsApp's ~14 days; those files are not encrypted like the database (see SECURITY.md). Set it to false to stop. When an app runs the bridge (WHATSAPP_BRIDGE_SUPERVISOR), the MCP server leaves transcription to that app: no offer and no terminal steps.

For apps that run the bridge (Mycelium Studio):

  • WHATSAPP_FULL_HISTORY=true asks your phone for the whole history when the device first links, so one link brings in your chats and their history.
  • WHATSAPP_DEVICE_NAME sets the name your phone lists under Linked devices.
  • WHATSAPP_EXIT_WITH_PARENT=true stops the bridge when the app that started it exits.
  • POST /api/auth/logout unlinks the device from your phone.
  • The MCP server's WHATSAPP_BRIDGE_PORT_FILE follows a bridge on a free port, and never falls back to another bridge.
  • Each release now attaches the MCP server as a wheel with its SHA-256.

Full details in CHANGELOG.md.

v0.5.1: find saved contacts by phone number

Choose a tag to compare

@adelaidasofia adelaidasofia released this 07 Oct 06:30
e9d4202

Find saved contacts by phone number

If search_contacts finds a contact by name but returns nothing when you search their number, this release is your fix.

Contacts that come from your phone's address book were stored with the number only inside their WhatsApp ID, and the search never looked there. A number typed the way a phone shows it, such as +57 300 123 4567, also matched nothing. Now a number is matched on its digits, with or without the country code, spaces or dashes. Contacts you already have are repaired automatically the first time the new bridge starts; there is nothing to re-sync.

Also fixed

  • Importing a Baileys store (--import-baileys) no longer names chats and contacts with numbers that are not theirs, and importing again over existing data keeps real names (#96).
  • With a CRM folder configured, CRM enrichment now reaches address-book contacts by phone too. A contact with no WhatsApp name of their own can then be exported to the vault under their CRM name.

How to update

Download the binary for your platform below, replace the one you have, and restart the bridge.

Full details: CHANGELOG

v0.5.0: Windows pairing fixed, plus backups and a transcription allow-list

Choose a tag to compare

@adelaidasofia adelaidasofia released this 07 Oct 05:40
875d0e6

Who should update

Everyone on v0.4.1 or earlier, and especially anyone who pairs the bridge on Windows or with a typed code. On v0.4.1 the bridge could crash on Windows while drawing the pairing QR, and requesting a typed pairing code failed with a 400.

New

  • WHATSAPP_WHISPER_ONLY_CHATS: transcribe voice notes only in the chats you name.
  • WHATSAPP_BACKUP_PATH now takes backups: encrypted, consistent snapshots of the live database, on a schedule set by WHATSAPP_BACKUP_INTERVAL_HOURS and WHATSAPP_BACKUP_KEEP.
  • /api/status reports how long the connection has been down, and a watchdog retries a connection that stays down.
  • MCP tools for groups, media download and history backfill.

Fixed

  • Windows: the bridge no longer crashes when it draws the pairing QR on a console with VT processing on, outside Windows Terminal.
  • --pair-phone and POST /api/auth/pair-phone no longer fail with 400: bad-request.
  • Photos and PDFs sent as part of a multi-file (album) message can be downloaded.
  • The calls table records calls; before this it rejected every row.
  • /api/status no longer reports a connection whose handshake was never confirmed.
  • The version stamps match the release (v0.4.1 reported itself as 0.4.0).

How to update

Download the binary for your platform below, replace the one you have, and restart the bridge.

Full details: CHANGELOG

v0.4.1 — WhatsApp stopped accepting the old client; update to reconnect

Choose a tag to compare

@adelaidasofia adelaidasofia released this 26 Aug 02:24
ba8e123

Update if your WhatsApp bridge stopped receiving messages

On 2026-08-24 WhatsApp stopped accepting the client version this bridge shipped with. If you are on v0.4.0 or earlier, your bridge is not connected, and it will not fix itself.

The failure is quiet on purpose-built monitoring: the process stays up, the API keeps answering from your local database, your phone stays paired, and /api/status still says authenticated: true. Only connected flips to false. WhatsApp returns 405 Client outdated, which whatsmeow classifies as non-retryable, so there is no retry loop and nothing recovers.

How to tell

curl -s http://127.0.0.1:8080/api/status

If it reports "connected": false with "authenticated": true, this release is your fix.

How to update

Download the binary for your platform below, replace the one you have, and restart the bridge.

Your existing pairing is preserved. No QR scan, no re-linking, no data loss — the session store carries over untouched. Verified against a live connection before publishing.

Building from source instead? The minimum Go version is now 1.26 (upstream whatsmeow and go.mau.fi/util both require it). Prebuilt binaries need no compiler.

Security

This release also closes an issue that exists in every earlier build. The previous whatsmeow pin passed an attacker-supplied URL taken from inbound message content to an arbitrary host during media download. Upstream removed it. The same range adds constant-time MAC comparisons, a certificate validity window, and a fix for a reachable crash.

If you are running an older build, update for this reason even if your connection currently works.

Two changes worth knowing about, both from upstream:

  • WhatsApp now sends call log history into your local store.
  • Two additional secrets are written at rest in the session database, alongside the identity keys already there.

Full detail, including the 104-commit upstream review, is in CHANGELOG.md and on #74.

Also in this release

  • The dependency review gate no longer reports a green check while skipping its own enforcement (#76).
  • The release pipeline now fails when a promised binary is missing, instead of publishing quietly without it — which is how v0.4.0 shipped without its Intel Mac build (#77).

v0.4.0 — Windows, macOS and Intel Mac all actually work now

Choose a tag to compare

@adelaidasofia adelaidasofia released this 19 Aug 22:32
0b2c898

This is the release to install. The previous one (v0.3.1, July 24) predates two significant fixes that have been sitting on main unreleased — including the one that stopped the vault export from silently dropping chats.

If you are installing on a Mac

Intel Macs now have a binary. There was no darwin-amd64 build before, so the "no compiler needed" path silently did not exist for you. Grab whatsapp-bridge-darwin-amd64; Apple Silicon takes whatsapp-bridge-darwin-arm64.

Expect one Keychain prompt on your second start. This is normal, not a failure. The first start creates the database key and just works. The next one asks:

security wants to access key "whatsapp-mcp-db-key" in your keychain.

Click Always Allow — not plain "Allow", which only covers that one start. You will not be asked again. Running headless (ssh, launchd, a container) where no dialog can appear? Set WHATSAPP_DB_KEY instead; see SETUP.md. Background and the open tradeoff: #70.

Fixed

  • The bridge could hang forever at startup on macOS. No secret-store call had a timeout, and the key lookup runs before the HTTP server binds — so a keychain call waiting on user authorization waited indefinitely, with nothing in the log to explain it. Measured on CI: 9 minutes 56 seconds before the harness killed it. Every such call is now bounded (WHATSAPP_KEYCHAIN_TIMEOUT_SECONDS, default 120s) and fails with a message that names the fix.
  • One control character in a group name failed the entire vault export on Windows. Group subjects and push names are set by other people and can contain a newline. On macOS and Linux that is a legal filename; Windows rejects it, and because the export is deliberately all-or-nothing, a single awkward group name took every other chat down with it.
  • A sender-chosen message ID could write files outside the media folder. WhatsApp message IDs come from the sending client, and they were used to build a file path unchecked.
  • Cross-origin requests are refused (#34). Binding to 127.0.0.1 kept the API off the network but not away from web pages you visit; a text/plain POST from any page was accepted and processed. Non-browser clients are unaffected — set WHATSAPP_ALLOWED_ORIGINS if a browser UI needs in.
  • check_prerequisites.sh no longer demands Go. It treated Go as required and quit on the first miss, so anyone installing from a prebuilt binary got a red FAIL Go not found and never saw the checks for the tools they actually needed.
  • Shell scripts survive a Windows clone. Without .gitattributes they arrived CRLF-mangled, so set -euo pipefail never applied and the prerequisite check exited 0 having verified nothing.
  • From the backlog, never before released: a transient keychain read failure could mint a new key over the real one and permanently orphan your encrypted message store (MYC-3694), and the vault export could drop entire direct chats while exiting 0 (MYC-3555).

Also

Prebuilt binaries for all four targets, a gofmt gate, a real-Keychain test on the macOS CI leg (which is what found the hang), one source of truth for the version string, and a release smoke test that can actually fail — the old one discarded its exit status twice.

Full detail in CHANGELOG.md.

v0.3.1 — keep chosen chats out of transcription

Choose a tag to compare

@adelaidasofia adelaidasofia released this 25 Jul 00:11
a76ce72

New: keep chosen chats out of voice-note transcription

Set WHATSAPP_WHISPER_EXCLUDE_CHATS to a comma-separated list and any chat whose name or JID matches one of those patterns is never transcribed. Matching is accent-insensitive and case-insensitive, so Mamá and mama both match, and it applies to both the live receive path and the backfill sweep through a single chokepoint.

WHATSAPP_WHISPER_EXCLUDE_CHATS="mama,familia,pablo"

Contributed by @Javi3rs in #40. Thank you.

The filter fails closed: if the chat lookup cannot be completed, the chat is treated as excluded and the voice note is not transcribed. Skipping a transcript is recoverable, transcribing a private voice note is not, so the uncertain case takes the safe direction. A chat that simply has no stored row yet is not treated as an error, so ordinary new chats still transcribe normally.

Internal

The backfill sweep now buffers its candidate rows and closes the result set before doing any further database work. The connection pool runs a single connection, so a nested query issued while the result set was still open would have waited on a connection its own caller held. Nothing released was affected by this, since the nested query arrives with the feature above. It is prevented rather than fixed.

Upgrading

Existing databases are unchanged. No migrations, schema version stays at 3. Replace the binary and restart. Leaving WHATSAPP_WHISPER_EXCLUDE_CHATS unset preserves current behavior exactly.

Everything in v0.3.0 is included, notably the fix for undecodable messages being silently dropped. If you are upgrading from v0.2.0 or earlier, read the v0.3.0 notes as well.

macOS: the released binaries are ad-hoc signed, not notarized

The macOS binary is built by CI and signed ad-hoc, so Gatekeeper will reject it after download. Running it from Terminal generally works, but launchctl bootstrap can refuse to load it when the downloaded file still carries the quarantine attribute.

Check for the attribute:

xattr -l ./whatsapp-bridge-darwin-arm64 | grep quarantine

If it is present, remove it:

xattr -d com.apple.quarantine ./whatsapp-bridge-darwin-arm64

Building from source avoids this entirely. Proper Developer ID signing and notarization is tracked and needs the signing credentials wired into the release workflow.

Verify any downloaded artifact against its published .sha256 file before running it.

v0.3.0 — no more silently dropped messages

Choose a tag to compare

@adelaidasofia adelaidasofia released this 24 Jul 23:41
10e0bd6

Fixed: the bridge could silently drop messages it could not decode

This is the headline of this release, and the reason to upgrade.

Any WhatsApp message type the bridge did not recognize (polls, events, view-once, edited messages, and others) had its payload discarded and was stored as an empty system row. There was no error and no log line, and nothing distinguished "this message genuinely had no text" from "I could not read this message". A message that existed for the user did not exist in the exported data, and because the loss happened at capture time it was not recoverable afterward.

Now an undecodable message is kept with an explicit marker naming the real message type, a warning is logged at ingest, and the vault export renders it as [Unsupported message: <type>] with its sender and timestamp, the same way an unrecoverable voice note is already marked. It is never a blank line and never silently omitted.

Messages that carry no user-visible text (protocol and encryption plumbing, such as group sender-key distribution) stay silent as before, so this does not add noise to exported chats.

Also in this release

  • /healthcheck now reports undecoded_total, undecoded_by_type, and legacy_empty_system, so anything the bridge cannot read is measurable rather than discovered by accident. legacy_empty_system counts pre-existing empty system rows already in the store.
  • Security: x/crypto 0.52.0 and x/net 0.55.0, clearing 7 critical, 2 high, and 5 medium advisories.
  • Windows: embedded migrations are read with path.Join rather than filepath.Join, fixing first boot on Windows.
  • New endpoint: GET /api/groups returns joined groups with participants and phone numbers.
  • CI: whatsmeow pin parsing repaired and a replace-directive bypass closed.

Upgrading

Existing databases are unchanged. This release adds no migrations, and the schema version stays at 3. Replace the binary and restart.

Rows already stored as empty system before this release are not rewritten. legacy_empty_system on /healthcheck reports how many exist. Decoding the message types that carry text, and backfilling those historical rows, are both still open.

macOS: the released binaries are ad-hoc signed, not notarized

The macOS binary is built by CI and signed ad-hoc, so Gatekeeper will reject it after download. Running it from Terminal generally works, but launchctl bootstrap can refuse to load it when the downloaded file still carries the quarantine attribute.

Check for the attribute:

xattr -l ./whatsapp-bridge-darwin-arm64 | grep quarantine

If it is present, remove it:

xattr -d com.apple.quarantine ./whatsapp-bridge-darwin-arm64

Building from source avoids this entirely. Proper Developer ID signing and notarization is tracked and needs an Apple Developer account before it can be wired into the release workflow.

Verify any downloaded artifact against its published .sha256 file before running it.

v0.2.0 — Windows support, live-refresh QR, pairing-code + headless auth API

Choose a tag to compare

@adelaidasofia adelaidasofia released this 14 Jul 02:57
7aac62a

The Windows release. Full changelog lives in CHANGELOG.md (Unreleased section = this version).

Added

  • Native Windows Credential Manager storage for the SQLCipher key (no extra install), with a real round-trip test on the windows CI runner; the WHATSAPP_DB_KEY override now genuinely works on every OS
  • Live-refreshing terminal QR: in-place redraw per rotation, Windows-safe rendering (ANSI block fallback outside Windows Terminal), automatic fresh codes on expiry — the bridge never dies mid-pairing anymore
  • --pair-phone +15551234567: pair by typed 8-char code (Android + iOS), no QR scanning needed
  • Headless auth API: HTTP server boots before pairing; auth_state on GET /api/status, GET /api/auth/qr, POST /api/auth/pair-phone, POST /api/auth/reconnect; logout auto-re-enters pairing
  • .env file support (documented forever, loaded never — now loaded; process env wins)
  • Cross-platform CI (ubuntu/macos/windows) + prebuilt bridge binaries attached to this release (see Assets — Windows users skip the C toolchain entirely)
  • scripts/check_prerequisites.ps1 + SETUP.md rewritten per-OS

Changed

  • WHATSAPP_WHISPER_BACKEND defaults to off — zero-config boot; the old local-cpp default demanded a ~3 GB model at startup. Set local-cpp explicitly if you relied on it.
  • Windows-reserved filename escaping in vault exports; per-OS install hints in error messages; structured bridge errors surfaced through the Python MCP; UTF-8 stderr on Windows

Binaries below are built by .github/workflows/release.yml on native runners, each with a .sha256.

whatsapp-mcp v0.1.0

Choose a tag to compare

@adelaidasofia adelaidasofia released this 20 May 02:46

Canonical Anthropic MCP bundle for whatsapp-mcp.

Install in Claude Desktop: double-click the .mcpb file.
Discoverable via registry.modelcontextprotocol.io at io.github.adelaidasofia/whatsapp-mcp.

Generated by Mycelium-MCP publishing pipeline 2026-05-19.