MyZap: a REST API that drives WhatsApp Web in a headless browser

WhatsApp automation through a browser with no interface

MyZap is presented as a free, fully open source REST API, and the README is in Portuguese, which is the first sign of where this project comes from. The English one line summary in the repository description is Free Open Source Whatsapp Api.

The mechanism is stated in one long sentence and it is the important part of the project. It uses WPPCONNECT, Whatsapp-WEB.JS and Venom-bot as a base: a virtual browser with no graphical interface that opens WhatsApp Web and executes all the commands through code, which is what makes automation of the functions possible.

That distinction matters for everything else in this review. There is no official WhatsApp API here, and no server-side protocol implementation. What there is, is a Chromium process with a real WhatsApp Web session in it, and an HTTP layer in front of it that translates REST calls into browser actions. The session is the state, and it can expire, be challenged or be signed out.

The repository is an Express application with the usual layers: routers, controllers, Models, migrations and seeders for the database, config and infra folders, an nginx configuration, a Swagger file with generated output, and separate engines, functions, clients and middlewares directories.

The primary language is JavaScript, the package declares the MIT licence, and the repository licence field itself is empty, so the manifest is the reference there.

Installing means provisioning a server, not adding a dependency

The 3.0 installation instructions are a sequence of server provisioning steps, and the first one is a large apt-get line that installs the shared libraries a headless Chromium needs.

apt update && apt upgrade && cd /opt && apt install -y curl nano git net-tools htop gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget build-essential apt-transport-https libgbm-dev nginx python3-certbot-nginx

The list includes the GTK and X11 stack, the sandbox libraries and the font packages, because Chrome will not start without them, plus nginx and the certbot nginx module, which suggests TLS termination is handled outside the application.

Node 20 is installed through the nvm script, and Chrome itself comes from Google's own deb package installed with gdebi.

cd /opt/api-whatsapp/ && sudo apt install gdebi -y
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && sudo gdebi google-chrome*

Then the application itself, the database schema, and the process manager.

npm i && npm audit fix --force

bash ./scripts/database.sh

bash ./scripts/start.sh

The default credentials are in the README: the user is [email protected] with the password your_token_api, which is a placeholder you are expected to replace.

The Docker image compiles its own browser

The container route is more self-contained, and the Dockerfile shows how the browser problem is solved there.

FROM node:20-bookworm-slim

WORKDIR /usr/src/app

ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

The base image is a slim Debian with Node 20, and the apt layer installs ca-certificates, chromium, chromium-driver, curl, ffmpeg, python3, g++ and make.

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        chromium \
        chromium-driver \
        curl \
        ffmpeg \
        g++ \
        make \
        python3 \
    && rm -rf node_modules \
    && npm install --no-audit --no-fund \
    && npm rebuild sqlite3 --build-from-source \
    && rm -rf /var/lib/apt/lists/*

Two details matter. The PUPPETEER_EXECUTABLE_PATH environment variable points the browser automation at the system Chromium rather than a downloaded one, so the image does not need a separate browser download step. And the npm rebuild sqlite3 --build-from-source line exists because one of the native dependencies will not have a prebuilt binary for this platform and has to be compiled, which is why g++, make and python3 are in the image at all.

The Compose file is minimal: one service built from the current context, the port mapping driven by environment variables, one volume for the session tokens, and a network with an alias so the service can be reached by name.

    ports:
      - ${MYZAP_HOST}:${PORT}:${PORT}
    volumes:
      - ${MYZAP_SESSION_LOCAL}:/usr/src/app/tokens

The Express application behind the endpoints

The dependency list describes the application clearly, and it is a large one for a wrapper around a browser.

Express is the HTTP layer, with cors, express-session, express-fileupload and express-pino-logger alongside it. Sequelize is the ORM, and there are migrations and seeders in the tree to go with it. Bull is the queue library, which means the project has background job handling for the slow parts of sending media and running browser actions. pino and pino-http provide structured logging.

For media, which is where a WhatsApp integration spends most of its complexity, there is ffmpeg and fluent-ffmpeg for audio and video handling, sharp for images, file-type for sniffing types, form-data for uploads and mime-types. There is qrcode for generating codes, request and request-promise alongside axios for outbound calls, dotenv for configuration, ejs for views, moment for dates and sha1 for hashing.

The wppconnect-team/wppconnect package is the actual automation engine, and it is the only dependency that matters conceptually. Everything else is plumbing around it.

The scripts in the manifest show how it runs and how it documents itself. Swagger output is generated from swagger.js with swagger-autogen, and the generated file is checked into the repository as swagger_output.json, so the API reference is committed rather than produced at deploy time. The dev script uses nodemon, the start script runs index.js directly, and release-it handles releases.

The session token is the state that must not be lost

The one volume in the Compose file is the interesting part of the deployment, and it points at how this system actually works.

The Compose file mounts ${MYZAP_SESSION_LOCAL} at /usr/src/app/tokens, and the tokens directory is where the browser session lives. That session is the authenticated WhatsApp Web login, and it is what allows the application to act as the account without a human present.

Two consequences follow. First, that directory has to be on persistent storage, because losing it means re-scanning a QR code and logging in again. Second, and more importantly, it holds credentials in effect, since the session is what authorises every action the API takes. The compose file makes it easy to mount a host directory, which is convenient for backups and easy to get wrong in terms of who on the host can read it.

The repository also carries an .env_exemplo file, an environment template, and a logs directory, plus files-received for inbound media. There are scripts for local runs and for starting the service, and separate startlocal.sh and cmdlocal.sh entry points that suggest a development workflow alongside the PM2 based production one.

The nginx configuration in the tree indicates that TLS and reverse proxying are expected to sit in front of the Node process rather than inside it, which is a sensible split for a long lived service.

No automated tests, and the manifest says so

The package manifest contains the test script, and it is the default placeholder.

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",

There is no test suite. The repository has no test directory.

For a wrapper around a browser automation library, that is worth weighing carefully. The upstream libraries it builds on have their own tests, but the layer above them, the mapping from a REST call to a browser action, is exactly where a version bump can change behaviour without any signal. A new version of the automation engine can change how a message is sent or how a media download behaves, and nothing in this repository would catch it.

That does not make the project unusable. It does mean that the burden of verification sits with whoever deploys it, and that an upgrade plan has to include testing your own flows rather than relying on the project to have done it.

The repository does contain a docs directory and a Swagger definition, so the API surface is documented even if it is not tested.

Version drift, the commercial tier and where support actually comes from

The version numbers tell a story worth reading carefully.

The default branch is named myzap2.0, while the README documents the 3.0 installation flow and lists a developer for the 3.0 line and another for the 2.0 line. The tagged releases are v3.0.1 from 2024-07-15, 2.0.0 from 2021-09-29 and 0.1.0 from 2021-04-13. The last push was on 2026-08-02, so work is still happening, but there has been no tagged release since July 2024.

So the branch you clone, the version the README describes, and the latest tag are three different things. Anyone adopting this needs to decide which of them they are installing, and that decision is not documented anywhere I could find in the repository.

The commercial side is explicit. The README asks where the full professional version is, and points at a white-label offering with support, an auto installer, automatic updates, more than 72 functions and, in the phrasing of the original, a pão de queijo. The open source project is the community edition of a commercial product, and that shapes what to expect: the open source version is what the maintainers use and support through WhatsApp groups and a Telegram chat, while the paid tier carries the installer and the update path.

There is also a PHP client published as a Composer package, jhowbhz/package-apigratis, for consuming the API from a PHP application.

The licence file situation is the other loose end. The manifest says MIT and the repository field for the licence carries no value, so the manifest is what governs, and it is worth confirming the terms of the upstream libraries it depends on, since those carry their own.

Editorial conclusion

Adopt MyZap when you need WhatsApp messaging from a backend system, when you can accept that the integration is an automated browser session rather than an official API, and when you are prepared to keep a Chromium process and a WhatsApp session alive on a server. Do not adopt it for anything that cannot tolerate a session expiring and needing a re-scan, and note that the project ships no automated tests, so an upgrade means testing your own flows. Before the first install, decide whether you will run the Docker image or the scripted setup, keep the session token volume on persistent storage, and read the version notes, since the default branch is myzap2.0 while the README documents the 3.0 flow and the newest tagged release is v3.0.1 from 2024-07-15.

Frequently asked questions

Official sources

1. billbarsch/myzap on GitHub
2. Issues
3. README
4. Releases