WAHA (devlikeapro/waha): a self-hosted WhatsApp HTTP API with three engines

The problem WAHA solves, and who it is aimed at

WhatsApp has no public HTTP endpoint that a hobbyist or a small team can call to send a message. The official route is the WhatsApp Business API, which comes with business verification and provider relationships. WAHA takes the other path: it runs a WhatsApp client on your own server and exposes the result as a REST API. The README describes it as an HTTP API you can install on your own server and run in less than 5 minutes, and the topics list on the repository includes ai-bot, whatsapp-bot and whatsapp-automation, which is a fair summary of the audience. If you are wiring a notification bot, an internal support tool, or an n8n workflow that needs to send and receive WhatsApp messages, WAHA is aimed at you. The unit of deployment is a Docker container, not a library you import, so the integration happens over HTTP from whatever language you already use.

Three engines, one HTTP surface: how WAHA actually works

The core design decision is that WAHA does not implement the WhatsApp protocol itself. It wraps one of three engines and normalizes them behind the same endpoints. WEBJS is browser based and is the default; the .env.example states WHATSAPP_DEFAULT_ENGINE=WEBJS and notes that GOWS or NOWEB are for better performance. NOWEB is described in the repository description as a websocket Node.js engine, and GOWS as a websocket Go engine. That distinction matters operationally. A browser-based engine carries the weight of a browser process, while the websocket engines speak the protocol directly. The same file sets WAHA_NAMESPACE=all so that sessions and apps survive a switch between engines, which tells you the engine is treated as a swappable transport rather than something baked into stored state. On top of the engines sits a NestJS application: package.json shows nest build, nest start, and a Jest setup split into unit and e2e projects. The HTTP layer is documented through Swagger, which the README points at on localhost:3000 after startup.

Installing WAHA from Docker and sending a first message

Docker is the only stated requirement. The README says the only thing you must have is Docker installed, and links to Docker's own installation instructions. Pull the free image first.

docker pull devlikeapro/waha

Then run it, publishing port 3000. The README notes the last log line should read that the WhatsApp HTTP API is running on http://[::1]:3000.

docker run -it --rm -p 3000:3000/tcp --name waha devlikeapro/waha

Open http://localhost:3000/ and you get the Swagger documentation. Create a session with POST /api/sessions; the README gives this payload.

{
  "name": "default"
}

Now call GET /api/screenshot and scan the QR code that appears with your phone's WhatsApp app. After a few seconds, call GET /api/screenshot again: if you get the screenshot of your instance, the session is live. Sending text uses POST /api/sendText, with the chat ID formed from the international number without the plus sign and the @c.us suffix. The README gives this curl example.

export PHONE=12132132130
curl -d "{\"chatId\": \"${PHONE}@c.us\", \"text\": \"Hello from WhatsApp HTTP API\" }" -H "Content-Type: application/json" -X POST http://localhost:3000/api/sendText

For anything beyond a throwaway container, the repository ships docker-compose.yaml, which mounts ./sessions and ./media as volumes, restricts the port binding to 127.0.0.1:3000, and reads environment variables from an .env file. That file is the difference between losing your session on every restart and keeping it.

Where WAHA stops being the right tool

The engines are unofficial clients, and that shapes the failure modes. A session is a linked device, so it can be unlinked from the phone side at any time, and the QR flow has to be repeated. The README's own quick start ends by telling you to get the screenshot to confirm you are ready, which is a manual check, not an automated health signal. The docker-compose.yaml comments show the storage question is real: sessions go to ./sessions by default, and the file carries commented PostgreSQL and MongoDB blocks for people who need sessions elsewhere. If you skip those volumes, the container is disposable and so is your login. The Plus image is pulled with docker login against devlikeapro, so the free image and the paid image are separate artifacts; the README's note that multiple sessions inside a single container are a Plus capability is the clearest boundary documented there. If your use case needs several WhatsApp accounts in one deployment, the free path is not the one described. Finally, if you need a provider that will answer a support ticket about a ban or an API change, WAHA is the wrong category of tool.

WAHA compared with the official WhatsApp Business API

The honest alternative is the official WhatsApp Business API, and the difference is not features, it is who owns the protocol. With the official API, Meta runs the client and you call a documented, versioned endpoint with a commercial relationship behind it. With WAHA, you run the client, you own the container, and you own every consequence of the session dropping. That trade buys you things the official route does not offer casually: no business verification to start, a Swagger page on localhost, and the ability to keep the whole thing on a private network. The docker-compose.yaml binds to 127.0.0.1 by default, which suggests the intended posture is a service behind your own reverse proxy rather than something exposed directly. If your requirement is a stable, contractually supported channel for customer communication at scale, the official API is the better fit and WAHA is a detour. If your requirement is a bot that sends messages from a server you control and you can tolerate re-linking a device, WAHA is the shorter path.

Maintenance, licence and the cost of staying current

The repository is not archived and the last push was on 2026-09-17, with releases 2026.8.2, 2026.8.1 and 2026.7.2 landing between 2026-07-29 and 2026-09-01. Release cadence is therefore monthly-ish, which for a project tracking someone else's protocol is close to the minimum viable rhythm. The licence file is Apache-2.0 at the repository root, but package.json carries "license": "UNLICENSED" and "private": true, and the docker-compose.yaml references devlikeapro/waha-plus behind a docker login. Read that combination carefully: the repository is Apache-2.0, while the Plus image is a separate distribution with its own access terms. Nothing here is legal advice, but the practical implication is that you should confirm which artifact you are actually deploying and under which terms before you build a product on it. Upgrading is not a simple pull either. The Dockerfile builds a Go component, uses a Rust nightly toolchain and wasm-pack for whatsapp-rust-bridge, and rebuilds sharp from source on x86-64 to drop the SSE4.2 requirement, so anyone building from source rather than pulling the image inherits that toolchain. The README's development section lists node>=22, Bun v1.3.9, Rust nightly-2026-01-30 and wasm-pack 0.14.0 as the versions to install.

Editorial conclusion

Adopt WAHA if you want WhatsApp behind an HTTP surface you control and you accept that the session lives in a container you must keep alive. Do not adopt it if you need an officially supported WhatsApp Business API with contractual guarantees; the README points to unofficial engines. Before building on it, confirm which engine you will run, whether the feature you need sits in the free image or in WAHA Plus, and where sessions and media are stored between restarts.

Frequently asked questions

Official sources

1. devlikeapro/waha on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases