Evolution API: a self-hosted WhatsApp REST API with Baileys and Cloud API channels

What Evolution API solves for teams that need WhatsApp in their own stack

Sending and receiving WhatsApp messages programmatically means choosing between two very different transports. The WhatsApp Web route, implemented here through the Baileys library, is free and works with an ordinary phone number, but it depends on the web version of WhatsApp and the README states it may have limitations compared with the official APIs. The official WhatsApp Cloud API from Meta is the supported business route, and the README notes it requires compliance with Meta's policies and may incur per-message costs.

Evolution API's answer is to expose both behind one REST surface. A client application, CRM or automation tool talks HTTP to a single service, and the service decides whether that instance is backed by Baileys or by Cloud API. That matters for teams already running a CRM or support desk: they do not want WhatsApp session handling, media download and webhook dispatch scattered across their own codebase.

The project is explicitly positioned as part of the Evolution Foundation ecosystem, and the README says it is used as a WhatsApp provider by Evo CRM Community. So the intended user is not a solo script author. It is a team that wants a messaging engine it can host, extend and point multiple downstream systems at.

Multi-provider architecture: channels, chatbots, events and storage

The README lays out the architecture as a four-branch fan-out from the API core. Channel integrations cover Baileys and Cloud API. Chatbot integrations cover Typebot, Chatwoot, OpenAI, Dify, Flowise and N8N. Event integrations cover WebSocket, RabbitMQ, SQS, NATS and Pusher. Storage integrations cover S3 and MinIO, with local storage also supported.

That shape is worth reading carefully, because it tells you where the coupling is. The API core is the only component that talks to WhatsApp. Everything else is a consumer or a side effect: a chatbot integration reacts to inbound messages, an event integration publishes what happened, and storage holds media that WhatsApp delivered. The README states that message queue support is configurable per instance, which means two instances on the same deployment can publish to different brokers.

Media handling is described as local or S3/MinIO, with automatic media download from WhatsApp and optional audio transcription via OpenAI. That last part is a real design decision: transcription is not a self-contained feature, it routes audio through an external AI provider. If your deployment has no outbound access to that provider, the transcription path is simply unavailable.

Authentication is layered. The README lists API key authentication via the apikey header, instance-specific tokens for WhatsApp connection authentication, and webhook signature validation for external integrations. The three are separate concerns and should be treated as such when you review a deployment.

Installing Evolution API with Docker and running it from the bundled compose file

The README gives a Docker path first. The image is published as evoapicloud/evolution-api:latest on Docker Hub, and the README's example maps port 8080 and reads configuration from an env file. The Dockerfile exposes 8080 and sets DOCKER_ENV=true, so the container is built to run with environment-driven configuration rather than a checked-in config file.

docker pull evoapicloud/evolution-api:latest
docker run -p 8080:8080 --env-file .env evoapicloud/evolution-api:latest

For anything beyond a smoke test, the repository ships a docker-compose.yaml that wires four services together: the API, a manager frontend, Redis and PostgreSQL 15. The API service depends_on redis and evolution-postgres, binds 127.0.0.1:8080 on the host, and mounts a volume at /evolution/instances. That volume is where instance state lives, so it is the thing you must back up.

services:
  api:
    image: evoapicloud/evolution-api:latest
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - evolution_instances:/evolution/instances
    env_file:
      - .env

The compose file also declares an external network named dokploy-network alongside its own evolution-net bridge. If you are not running Dokploy, that external network reference will fail on `docker compose up` until you either create it or remove it from the file. This is the kind of detail the README does not call out, and it is the first thing that breaks a copy-paste deployment.

Configuration comes from .env. The example file sets SERVER_PORT=8080, DATABASE_PROVIDER to one of postgresql, mysql or psql_bouncer, and DATABASE_CONNECTION_URI in the form of a Prisma connection string. It also defines TELEMETRY_ENABLED, which defaults to true, and PROMETHEUS_METRICS, which defaults to false.

The non-Docker path requires Node.js 20+, PostgreSQL or MySQL, and Redis as recommended. The README's sequence is to clone the repository, run npm install, copy .env.example to .env, then set the database provider and run the Prisma steps.

export DATABASE_PROVIDER=postgresql
npm run db:generate
npm run db:deploy
npm run dev:server

The db:generate and db:deploy scripts are not plain Prisma commands. They go through runWithProvider.js, which substitutes DATABASE_PROVIDER into the schema and migration paths. The deploy script removes ./prisma/migrations and copies the provider-specific migration directory into its place before running prisma migrate deploy. That is a destructive copy, not an additive migration, so do not run it casually against a database you care about.

Where Evolution API stops being the right tool

The Baileys channel is the weak point, and the README is honest about it without spelling out the consequences. Because it relies on the web version of WhatsApp, it is not a supported integration path in the way the Cloud API is. Session loss, re-authentication and behaviour changes on WhatsApp's side are operational realities of that route, and nothing in the repository's top-level files suggests a mitigation beyond keeping the instance volume intact.

The DEL_INSTANCE setting in .env.example is a related trap. It controls how long an instance is deleted from memory when there is no connection, defaulting to five minutes, and the file notes you can set it to false to disable expiry. A deployment that leaves the default in place and expects a disconnected instance to stay resident will behave differently than the operator assumes.

There is also a licensing ambiguity worth flagging. The repository metadata reports the licence as NOASSERTION, while the README displays an Apache 2.0 badge and the repository contains LICENSE, NOTICE and TRADEMARKS.md files. Those two signals do not agree on their face. Anyone embedding this in a commercial product should read the actual licence files rather than trusting the badge.

Finally, this is not a managed service. There is no uptime commitment in the README, and the project points to a HostGator VPS partnership for hosting rather than offering one. If your requirement is a vendor who answers when messages stop flowing, Evolution API is the wrong shape of product.

Evolution API versus going straight to the WhatsApp Cloud API

The obvious alternative is to skip the wrapper and call Meta's WhatsApp Cloud API directly. The difference is not feature parity, it is what you have to build. Calling Cloud API directly means you implement webhook receipt and verification, media retrieval, token lifecycle and per-instance configuration inside your own application. You also lose the Baileys option entirely, so every number you onboard must be a Cloud API number.

Evolution API's value is that it already implements that layer and adds a second transport next to it. The cost is a service you now operate: a Node process, a PostgreSQL or MySQL database behind Prisma, Redis, and a persistent volume for instance state. If you only ever need one WhatsApp number and one webhook endpoint, that stack is more moving parts than the problem requires, and direct Cloud API integration is the smaller commitment.

The trade-off flips when you have several numbers, several downstream consumers, or a mix of Baileys and Cloud API instances. At that point the per-instance configuration and the event fan-out to RabbitMQ, SQS, NATS, Pusher or WebSocket start paying for themselves, because you would otherwise be rebuilding that routing in application code.

Maintenance, releases and what an upgrade actually costs

The last push to the repository was on 2026-07-14, and the most recent releases listed are 2.4.0-rc2 from 2026-05-17, 2.4.0-rc1 from 2026-05-06 and 2.3.7 from 2025-12-05. The package.json still declares version 2.3.7, so the published package metadata lags the release tags. Pin an explicit tag rather than :latest if you need reproducible deployments.

The upgrade surface is wider than a typical Node service. The database layer is Prisma with provider-specific schemas and migrations, and the migration scripts copy directories rather than applying incremental patches. Upgrading across a release that changes the schema means running the provider-aware deploy script and accepting that it replaces ./prisma/migrations. Test the upgrade against a restored copy of your database before touching production.

The Dockerfile labels itself version 2.3.1, which is another place where version strings in the repository do not line up. Treat the git tag as the source of truth.

Telemetry is on by default. The README states that the project collects anonymous data covering routes used, most accessed routes and API version, and that no sensitive or personal data is collected. TELEMETRY_ENABLED=false in .env turns it off. On the licence side, the README badge says Apache 2.0 while the repository metadata reports NOASSERTION, and the presence of a TRADEMARKS.md file suggests the project distinguishes code licensing from name usage. Read LICENSE, NOTICE and TRADEMARKS.md together before redistributing.

Editorial conclusion

Adopt Evolution API if you need a self-hosted HTTP layer over WhatsApp and are willing to run PostgreSQL or MySQL, Redis and a persistent session store yourself. Do not adopt it if you need a vendor SLA on message delivery, or if Baileys session instability is unacceptable for your use case. Before committing, verify the exact licence terms in the LICENSE and NOTICE files, confirm which release tag you will pin (2.4.0-rc2 is a release candidate, 2.3.7 is the last non-RC tag listed), and check that your database provider has matching Prisma migrations under prisma/.

Frequently asked questions

Official sources

1. evolution-foundation/evolution-api on GitHub
2. Issues
3. Project website
4. README
5. Releases