An unofficial, test-first fork of 2.3.7 that fixes several open issues, offered for upstreaming

Start with FORK.md and the linked fork pull request #2 to review the proposed changes by area, then inspect docs/LIVE-CHECKS.md and the fork-tests workflow for validation details. There is no single completion target: upstreaming would require maintainers to select and adapt one or more areas to the project's preferred branch and conventions.

Hi, and thank you for Evolution API. While fixing problems I hit with Baileys, I ended up with a public fork that I would like to share and offer back.

What it is, and what it is not

• An unofficial fork: https://github.com/AlmogCohen/evolution-api (default branch fork/2.3.7). Not endorsed by Evolution Foundation; the licence is unchanged and NOTICE carries your attribution and the modifications.
• It is the 2.3.7 tag (the same code as main) plus about 70 changes. It stays on the 2.3.x line and does not include develop.
• Baileys is pinned to 7.0.0-rc14. 2.3.7 ships rc.9, which is inside the affected range of CVE-2026-48063 (GHSA-qvv5-jq5g-4cgg).
• No database changes: prisma/ is identical to 2.3.7, and a session linked on the stock 2.3.7 image kept working after switching the same volume and database to the fork.

How it is built

• A vitest harness runs Evolution's own TypeScript source against the real Baileys and its event buffer, fed WhatsApp-side inputs (history-sync protos, app-state patches).
• Every change is two commits: a test: commit that reproduces the bug and fails, then a fix: or feat: commit that turns it green with the rest of the suite still green. CI runs typecheck and tests on every pushed commit, so each test commit's red run sits in Actions next to its fix's green run.
• A weekly job runs the suite against the newest Baileys release, before anyone bumps the pin.
• Some behaviour is checked against a real phone: the session is recorded, scrubbed of personal data, and replayed as a test fixture (docs/LIVE-CHECKS.md).

FORK.md lists every change and its limits.

What changed, by area

Contacts, labels, groups

• App-state sync keys are reloaded with fromObject in all three auth stores, so labels, saved names, mutes and archives keep syncing after a restart. Fixes #2576, likely #2384 in part; the same change as #2685, #2610 and #2593.
• Group updates reach subscriptions stored as GROUP_UPDATE, in all seven transports and the global configs, without renaming stored values (the bug in #2652).
• group-participants.update reads Baileys 7 participant objects, so participantsData carries a real jid and phoneNumber again (the path added in #2025).
• chats.update / chats.set / chats.upsert webhooks carry archived, pinned and muteEndTime (the webhook half of #2743).
• Every @lid to phone mapping Baileys learns is forwarded on contacts.upsert, including those the event buffer drops from history (for #1872).
• Group metadata is cached from groups.update, and profile pictures are looked up once per contact per hour, at most four at a time (helps #1883).

Messages

• A getMessage miss or failed lookup answers nothing, so a retry no longer relays an empty message. Fixes #2705 and the empty-retry part of #2706; the same change as #2728 and #2623.

Media and proxy

• Media downloads, uploads and the WhatsApp Web version fetch go through the instance's proxy, never the server's own address. Proxied uploads work with Baileys rc13+ (the bug in #2734).
• Expired media is recovered: the phone is asked to re-upload on a CDN 404/410, and on a 403 only when the link has expired, with the media key as bytes and the chat named by the @lid the phone stores. In a live check, 7 of 8 files 30 to 180 days old came back byte-identical. Covers two of the three causes in #2465; the Baileys side is offered as WhiskeySockets/Baileys#2834 and WhiskeySockets/Baileys#2835 (for WhiskeySockets/Baileys#2767).
• getBase64FromMediaMessage takes an optional reupload: false, and a failed download says whether it asked the phone and why the phone refused.
• A failed download answers The media could not be downloaded (HTTP <status>) instead of Baileys' error text, which carries the signed media link; the errors webhook and the S3 error line get the same.

Sessions and connections

• A logout or delete while the socket is down keeps the session until WhatsApp is told, so the device leaves the phone's Linked devices (202 PENDING meanwhile). Includes #2520; covers part of #2508.
• Reconnects back off from 1s to 60s, the version fetch times out after 10s, and an instance never runs two sockets (the bug in #2656; related to #2134, #2184, #2430 and the idea in #2732).
• One pairing code per connect attempt, and a fresh QR budget per attempt (#2100).
• A database error or a failed creds write never replaces a linked session with a fresh one.
• Signal key files and the pending-logout marker are replaced whole (temp file, fsync, rename), so a crash, a full disk or two overlapping writes never leave a torn or empty key file. A crash test that SIGKILLs a writer 64 times found 26 torn and 6 empty files on the old code and none after. Possibly related to #2518.

Logs

• At LOG_LEVEL=ERROR,WARN the fork's own lines and Baileys' error lines carry no message text, phone numbers, JIDs, push names or media URLs (not a guarantee: some inherited code, such as the integrations, still logs raw errors).

How to try it

There is no published image; build it from source:

git clone https://github.com/AlmogCohen/evolution-api.git
cd evolution-api
docker build -t evolution-fork .
cp .env.example .env   # set DATABASE_CONNECTION_URI, AUTHENTICATION_API_KEY and the Redis settings
docker run -d --name evolution-fork -p 127.0.0.1:8080:8080 --env-file .env \
  -v evolution_instances:/evolution/instances evolution-fork

In an existing Compose deployment, point the api service's image: at evolution-fork, keeping the database and instances volume. Tests: npm ci, DATABASE_PROVIDER=postgresql npm run db:generate, npm test (a few need a local Postgres, FORK_TEST_PG_URL).

Upstreaming

I would be glad to open pull requests, one per area or smaller, against develop or a 2.3.x branch as you prefer, adapted to your conventions, with or without the test harness. If some are unwanted or already solved differently on develop, tell me and I will drop them. Known gap: pairing through companion_reg_refresh (#2727, WhiskeySockets/Baileys#2737) is not in the fork.

Links

• Fork: https://github.com/AlmogCohen/evolution-api
• All changes as one diff against 2.3.7, commit by commit with CI: https://github.com/AlmogCohen/evolution-api/pull/2
• The fork as posted here (a fixed snapshot): https://github.com/AlmogCohen/evolution-api/tree/fork-2.3.7-2026-09-29
• Change list: https://github.com/AlmogCohen/evolution-api/blob/fork/2.3.7/FORK.md
• Live-check protocol and results: https://github.com/AlmogCohen/evolution-api/blob/fork/2.3.7/docs/LIVE-CHECKS.md
• CI history: https://github.com/AlmogCohen/evolution-api/actions/workflows/fork-tests.yml