Evolution API is an open-source REST API that puts WhatsApp behind HTTP endpoints you can call from anything. The decision that matters is not whether to run it, it is which connection type you use: the Baileys mode that drives WhatsApp Web unofficially and can get numbers banned, or the official Cloud API that costs money and does not.
The project is widely used, particularly alongside workflow automation tools, and the documentation covers the endpoints well. What it does not spell out is the operational and account risk, which is the part worth understanding before you build a business process on it.
Table of contents
- What it is and what it replaces
- Baileys versus the Cloud API, which is the whole decision
- Running it
- Webhooks, and designing for the failures
- Is self-hosting the right call
- How this fits the rest of the stack
- FAQ
What it is and what it replaces
Evolution API wraps WhatsApp messaging in a conventional REST interface. You create an instance, connect a WhatsApp account, and then send and receive messages through HTTP calls and webhooks rather than through any WhatsApp client.
It has grown beyond a single-purpose wrapper and now supports multiple messaging providers and integrations with chatbot platforms, queues, and object storage. In practice most deployments use a narrow slice: send a message, receive a message, fire a webhook.
What it replaces is a category of brittle solutions: browser automation driving WhatsApp Web, a phone in a drawer running an app, or a paid intermediary charging per conversation on top of what WhatsApp already charges.
Where it fits most often is as the messaging layer under an automation tool. A webhook arrives, a workflow decides what to do, and a message goes out, with none of the participants knowing or caring that WhatsApp is involved.
Baileys versus the Cloud API, which is the whole decision
Two connection types, with very different risk profiles.
Baileys mode reimplements the WhatsApp Web protocol. You link it by scanning a QR code with a normal WhatsApp account, and it is free. It is also unofficial, unsanctioned, and against WhatsApp’s terms of service. Numbers used this way are banned regularly, sometimes within days, particularly when sending to people who have not messaged first.
Cloud API mode uses Meta’s official Business API. It requires a verified business account, message templates approved in advance for conversations you initiate, and per-conversation pricing. It is sanctioned, and your number is not at risk for using it as intended.
The honest guidance: Baileys is fine for internal tooling, personal projects, and situations where losing the number is an inconvenience rather than a crisis. It is a bad foundation for anything a business depends on, because the failure mode is not downtime, it is permanent loss of the number and its message history.
- Never use a personal number or the company’s main number in Baileys mode.
- Assume any number you connect may be banned without warning or appeal.
- Sending unsolicited messages accelerates a ban dramatically.
- Keep the contact list and message history exported somewhere, because you will not get it back.
The pattern that gets people is a proof of concept on Baileys that quietly becomes production. Nobody decides to bet the business on it; it just never got migrated.
Running it
Evolution API is distributed as a container and needs a database, a cache, and a publicly reachable HTTPS endpoint for webhooks.
services:
api:
image: atendai/evolution-api:latest
ports:
- "8080:8080"
environment:
AUTHENTICATION_API_KEY: generate-a-long-random-key
DATABASE_ENABLED: "true"
DATABASE_PROVIDER: postgresql
DATABASE_CONNECTION_URI: postgresql://user:pass@db:5432/evolution
CACHE_REDIS_ENABLED: "true"
CACHE_REDIS_URI: redis://cache:6379
WEBHOOK_GLOBAL_URL: https://your-app.example.com/webhooks/whatsapp
WEBHOOK_GLOBAL_ENABLED: "true"
volumes:
- evolution_instances:/evolution/instances
volumes:
evolution_instances:The volume matters. Session data for connected instances lives there, and losing it means re-scanning the QR code for every instance, which for Baileys connections is a manual step someone has to perform with a phone.
Creating an instance and sending a message is straightforward once it is up.
# Create an instance.
curl -X POST https://api.example.com/instance/create \
-H "apikey: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"instanceName": "support", "integration": "WHATSAPP-BAILEYS"}'
# Send a text message.
curl -X POST https://api.example.com/message/sendText/support \
-H "apikey: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"number": "447700900000", "text": "Your order has shipped."}'Note that the API key authenticates every call and grants full control, including reading messages. Treat it as a credential of the same weight as a database password: environment variable, never in the repository, rotated if exposed.
Webhooks, and designing for the failures
Incoming messages arrive as webhook POSTs to a URL you supply, which means your endpoint must be publicly reachable over HTTPS and must respond quickly.
Three things to get right, all of which are learned the hard way otherwise.
- Respond immediately and process asynchronously. Doing the work inline means a slow downstream call causes timeouts and redelivery, which produces duplicate handling.
- Deduplicate on message ID. Redelivery happens, and a customer receiving the same automated reply three times is a visible failure.
- Verify the request. The endpoint is public, so anything on the internet can post to it. Check a shared secret or restrict by source.
The other operational reality is reconnection. Baileys sessions drop, particularly when the linked phone is offline for a long period, and a dropped session stops delivering messages silently. Monitor connection state rather than assuming it, because the first sign otherwise is a customer complaining that nobody replied.
A simple health check that polls instance status and alerts on a disconnected state saves more trouble than any amount of retry logic elsewhere.
Is self-hosting the right call
In favour: no per-message markup beyond what WhatsApp itself charges, message content stays on infrastructure you control, and you can integrate at whatever depth you want rather than what a vendor exposes.
Against: you own the uptime, the upgrades, the session reconnections, and the database backups. And if you chose Baileys, you own a ban risk that no amount of good engineering removes.
The arrangement that works for most teams: use the official Cloud API for anything customer-facing and commercially important, and keep self-hosted Evolution API as the integration layer in front of it, so your application code does not care which provider is underneath. That gives you the operational control without the account risk.
The infrastructure required is modest and specific: a service to run the container, a Postgres database, a cache, storage for session data, and a domain with a certificate. All ordinary line items.
How this fits the rest of the stack
The pieces here are a container to run, a managed Postgres for its data, and storage for session state, plus whatever service consumes the webhooks. Costing those separately makes it much clearer whether self-hosting beats a per-message vendor, since the comparison usually omits the database and the attention. Note that Redis is not among the managed databases on RunxBuild, so a cache would run as a container alongside the service. The RunxBuild hosting calculator shows the service, database, and storage as separate line items.
Useful related references:
- Deploy a Node.js API for Free on RunxBuild
- Deploy a .NET API for Free on RunxBuild
- Namecheap API for Developers: The Part the Docs Skip
- Services on RunxBuild
FAQ
Is Evolution API free?
The software is open source and free to run. You pay for the server, database, and cache it needs, and for WhatsApp itself if you use the official Cloud API, which charges per conversation.
Can my number get banned using Evolution API?
In Baileys mode, yes. It drives WhatsApp Web unofficially and against the terms of service, and numbers are banned regularly, especially when messaging people who did not message first. Never connect a personal or primary business number this way.
What is the difference between Baileys and the WhatsApp Cloud API?
Baileys is an unofficial reimplementation of the WhatsApp Web protocol, free and unsanctioned. The Cloud API is Meta’s official interface, requiring a verified business account and approved templates, charging per conversation, and carrying no ban risk when used as intended.
What does Evolution API need to run?
A container runtime, a Postgres database, a Redis cache, persistent storage for session data, and a publicly reachable HTTPS endpoint so webhooks can be delivered.
Why do my Evolution API webhooks fire twice?
Redelivery after a slow or failed response. Return a success status immediately and process asynchronously, and deduplicate on the message ID so a repeat delivery does not repeat the action.