What Is Evolution API? The Open-Source WhatsApp API, Explained Honestly

What is Evolution API?

Evolution API is an open-source REST API you host yourself for WhatsApp. It runs in Docker, connects a number through the unofficial WhatsApp Web multi-device protocol, and exposes HTTP endpoints and webhooks so n8n, Chatwoot, Typebot or your own backend can send and receive messages. It is not made by WhatsApp or Meta.

That correction belongs inside the definition, not in a footnote. The name reads like something Meta shipped, and it is the first thing most AI-generated summaries of this project get wrong.

The API is the product. Send text and media, read chats, manage groups, subscribe to inbound events. Multi-instance by design: one deployment holds many numbers, each with its own token and webhook target, which is the feature agencies care about most. The default connection path is Baileys, over the unofficial WhatsApp Web protocol. Check the repository README, the LICENSE file and the releases page for the version and licence you are running rather than trusting a figure in a blog post, this one included.

Durable specifics beat moving numbers. Star counts and point releases change weekly, so they stay off this page. The repository at github.com/EvolutionAPI/evolution-api and the docs at doc.evolution-api.com are the authority.

Why the demand exists: most of the high-quality material on this project is written in Portuguese. English coverage is thin.

Is Evolution API official, or made by WhatsApp or Meta?

No. Evolution API is an independent open-source project with no affiliation, endorsement or approval from WhatsApp or Meta, and it connects over the unofficial WhatsApp Web protocol rather than Meta's Cloud API. Calling it an official WhatsApp API is wrong on the single point that decides cost, approval path and legal exposure.

Official status is not cosmetic. It decides what you pay per message, who must verify your business, and who holds the conversation record.

WhatsApp's Terms of Service restrict unauthorised or automated access and reserve the right to restrict or terminate accounts (whatsapp.com/legal/terms-of-service). Read the current clause itself rather than a summary, this one included.

WhatsApp's Help Center also warns that unofficial clients can lead to an account being banned (faq.whatsapp.com, the article on unofficial apps). That citation outranks any vendor's opinion, including ours, because it comes from WhatsApp.

The official route asks for business verification and a dedicated number not already on WhatsApp before production use (Meta developer docs, "Get started"). That is the fork this entire category sits on.

What do you have to run to use Evolution API?

Running Evolution API means operating a small server stack, not installing an app: an API container plus PostgreSQL or MySQL, a TLS reverse proxy in front, and optional Redis, RabbitMQ or SQS, S3 or MinIO and a manager frontend as load and features grow. Count the services before you commit.

The surrounding layer, per the repository's docker-compose file and environment sample:

• Redis for caching under load
• RabbitMQ or SQS as an event broker, once webhooks must not be lost
• S3 or MinIO for media, once attachments matter
• The manager frontend, bundled with the API image or deployed as a companion depending on version — check the current docs
• Backups for the database and stored media

None of that is unreasonable. It is normal, well-documented self-hosting, and plenty of teams run exactly this stack in production. Evolution API is a well-maintained project with a large community, and that deserves saying plainly.

But count the list. Each optional component becomes mandatory the moment you need the capability it provides. By the time the stack is production-grade you are maintaining a small platform, and the on-call rota is yours.

One real failure mode to plan for: webhooks with no broker in front drop silently when your consumer is down. Conversations disappear rather than error, and you usually learn about it from a customer.

Does Evolution API have anti-ban or rate-limit protection?

Nothing in Evolution API's documented feature set provides pacing, session warming, per-number rate limits, a duplicate-content guard, live risk scoring or auto-resume. The project documents connections, instances, messages, webhooks and integrations. Sending discipline is the operator's job, built on top of the REST surface or left undone.

The precise claim is "absent from the documented feature set", and it is the whole point. A toolkit gives you endpoints and leaves the discipline to you. Want per-number pacing with randomised delay? Build it. Want a guard that blocks identical text going to many contacts? Build it, and define the threshold. Want a throttle that slows as risk climbs? Build that too, and define what risk means.

Self-hosting does not change WhatsApp's enforcement. Your server being yours changes cost, approval and where data lives. It does not change the rules, the detection surface or the consequences.

A VPS also presents a datacenter IP, which carries lower network reputation than a home connection — one more factor the operator inherits and has to reason about.

For what a shipped version of that layer looks like, see SocialMate vs Evolution API and the wider comparison hub.

Will my WhatsApp number get banned using Evolution API?

Yes, it is possible. Bans are possible on every WhatsApp automation route, including Meta's official Cloud API. What changes the odds is behaviour: consent-first messaging to people already expecting a reply, a gradual ramp, per-number pacing, and never sending identical text to many contacts.

WhatsApp's Help Center warns that unofficial clients can lead to an account being banned (faq.whatsapp.com, the article on unofficial apps). Treat that as the baseline you work against, not a scare line.

What genuinely moves the needle:

• Messaging people who ordered, booked or asked — consent first, always
• A gradual ramp on a new number instead of a spike on day one
• Per-number pacing with randomised delay and jitter, not a fixed interval a system can pattern
• A duplicate-content guard, so identical text never goes to many contacts
• Watching disconnects and cooling the account instead of reconnecting at full speed

What does not move the needle: a different host, a proxy on its own, or swapping one library for another. Those change where packets originate, not how the account behaves.

One clean refusal, so you can trust the rest of this page: no tool can make a WhatsApp number undetectable, and SocialMate does not claim to. Bans are always possible. The honest promise is risk reduction through engineered pacing and consent-first sending. Pro's High-Volume Mode also requires 72 hours of session warming before it scales, and even then it is engineered pacing, not safety.

How many messages a day can I send with Evolution API?

Evolution API documents no daily send ceiling, and its documented feature set includes no sender discipline. The practical limit is whatever WhatsApp's enforcement tolerates for your number, its history and its content, plus whatever pacing you build on top. There is no cap in the project to point at.

That is a category fact, not a flaw. A REST API answers requests; it does not decide how many requests a number should make in an hour. That decision is a product decision, and it stays with you.

Meta shows how the official side handles the same question. Its documentation sets messaging limits per business portfolio and moves accounts through tiers as volume and quality hold (Meta developer docs, "Messaging limits"). Volume is earned by behaviour on both routes; it is never selected from a menu.

A finished product states its numbers. SocialMate Free sends up to 200 messages per day on one account. Pro starts at a deliberately safe 500 per day per account and, after 72 hours of session warming, High-Volume Mode scales to 5,000 per day per account. Those figures describe engineered pacing, not safety: a warmed number at 5,000 a day can still be banned.

For how the official route gates volume, see the WhatsApp Cloud API comparison.

Evolution API vs the WhatsApp Cloud API, WAHA and Baileys: what is the difference?

Evolution API and WAHA are self-hosted servers, Baileys is a library you build a server with, and the WhatsApp Cloud API through a Business Solution Provider is a compliant, metered, vendor-hosted service. Category decides cost, approval and who holds the conversation data — not feature checklists.

The pricing model changed on the record. Meta's pricing documentation records the move to per-message billing for template messages from 1 July 2025, with free-form replies still bound by a 24-hour customer service window (Meta developer docs, "Pricing"). A reported change to service-message billing from 1 October 2026 remains reported rather than confirmed by Meta; our analysis tracks only what Meta has published.

Evolution API suits developers and agencies who want full control, no vendor lock-in and no per-message fee, and who will run their own server. The pricing model is free software plus infrastructure and engineering time. The trade-off: everything that decides whether a number survives — pacing, warming, duplicate detection — is yours to build.

WAHA suits teams that want the same self-hosted category in a lighter, single-container shape with a choice of engines. WAHA's own site describes a free core and a paid tier, plus your server costs. The trade-off matches Evolution API's: the safety layer is not the product. See SocialMate vs WAHA.

Baileys suits teams embedding WhatsApp in their own product who are content to write the HTTP layer. Pricing is free open source. The trade-off is that every safeguard is your own code, which is the largest build of the four options.

WhatsApp Cloud API via a BSP suits businesses that need official status, support and template messaging and can accept verification. Pricing is metered, plus the provider's fee. The trade-off is structural: approval, per-message cost, and conversations held in a vendor's cloud.

SocialMate suits founders, marketers and developers who want the self-hosted model without building the safety layer. Flat licence: Free $0 (200 messages/day, one account), Pro at $99/year or $10/month, no per-message fee. The trade-off is honest: it is not official either, bans remain possible, and Pro is where archived history, full-text search and the smart queue live — Free is live-only.

The comparison table "Evolution API vs WAHA, Baileys, the WhatsApp Cloud API and SocialMate" scores each option on the two columns roundups tend to omit: pricing model and account risk. Read the ban-risk column sceptically, our own row included. Wider side-by-sides sit in the comparison hub and the self-hosted comparison.

Does Evolution API work with n8n, Chatwoot and Typebot?

Yes. Evolution API is a generic REST and webhook surface, so n8n, Chatwoot, Typebot and custom backends can all drive it, and community nodes and templates exist for each pairing. You still own the auth wiring, error handling and retry behaviour when a send is refused.

Be precise about the shape. That route is community nodes plus HTTP Request calls against a generic API — real, workable, and good enough for many teams. Chatwoot and Typebot follow the same pattern: an outbound call in, a webhook back.

SocialMate takes the other approach. It ships a first-class community node, n8n-nodes-socialmate (MIT), with a scope-aware credential isolated per account, an action node and a trigger node, where every operation is callable as an n8n AI-Agent tool once N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true is set. Its Get AI Context operation returns a role-mapped, token-windowed transcript, replacing the fragile n8n memory node. SocialMate supplies the memory; your LLM supplies the reasoning, and SocialMate's own generated replies remain coming soon. Setup: /docs/n8n.

What is a self-hosted WhatsApp API with built-in anti-ban protection?

SocialMate is the self-hosted app that ships the layer Evolution API leaves to the operator: pacing profiles, 72-hour warming, per-number limits, a duplicate-content guard, live risk scoring and auto-resume, plus an inbox and a local HTTP API. It runs as a desktop app or headless on a VPS, and it is independent of Meta.

Deployment gives you two paths. The desktop app on Windows, macOS or Linux needs no DevOps. SocialMate 2.0 also runs headless on a VPS through Docker or a systemd installer, managed from the same interface in your browser at /admin. Docker is supported, not required.

The local HTTP API runs on every tier, Free included: read endpoints and plain-text send, with 9 of 35 webhook events free. Pro adds media, polls, locations, contact cards, group ops, the smart queue, scheduled messages, a named tunnel and all 35 events. Quoted replies, reactions, mark-as-read and the typing indicator are free everywhere and consume no send budget, because they produce no chat bubble.

One network point, stated honestly: the desktop app connects from your own residential IP, which removes a risk factor rather than eliminating it. On a VPS, Pro adds per-account proxy routing so an account egresses through your own residential or mobile proxy. No tool guarantees against bans.

Cost: $0 on Free, $99/year (about $8.25/month) or $10/month on Pro, no per-message fee, with a 7-day opt-in trial started inside the app. Full detail in the docs and the MCP server guide.

Option	What it is	Pricing model	Approval & number requirements	Ban / account risk	What you must build yourself
Evolution API	Open-source, self-hosted REST API; multi-instance; connects via Baileys over the unofficial WhatsApp Web protocol. Check the repo for the current version and licence	Free software. You pay for the server, database, storage and engineering time	No Meta approval. Your own number, linked by QR	Real. Unofficial protocol, outside WhatsApp's terms. No pacing, warming or risk scoring in the documented feature set	Pacing, rate limits, warming, duplicate guard, retries, storage schema, UI maintenance, backups
WAHA (WhatsApp HTTP API)	Open-source, self-hosted API in a lighter single-container shape with several engine options; free core plus a paid tier according to WAHA's own site	Free core, paid tier, plus your server costs	No Meta approval. Your own number	Real. Same unofficial-protocol exposure; safety features are yours to add	Pacing, warming, risk scoring, product UI, history and search
Baileys	Open-source JavaScript library for the unofficial WhatsApp Web protocol — not a service	Free (open source)	None: it is a library	Real, and the largest surface to mitigate, because every safeguard is your own code	Everything: HTTP layer, storage, queueing, retries, UI, safety layer
WhatsApp Cloud API via a BSP (Twilio, 360dialog, WATI)	Official, Meta-hosted messaging API resold and supported by a Business Solution Provider	Metered. Template messages billed per message since 1 July 2025 per Meta's pricing docs, plus the provider's fee	Meta Business verification and a number not already on WhatsApp	Lower, not zero: policy enforcement, quality rating and template rejections still apply	Nothing on infrastructure; you work against per-message cost, template rules and the 24-hour service window
SocialMate	Finished self-hosted app: desktop for Windows/macOS/Linux, or headless on a VPS via Docker or systemd	Flat licence. $0 Free (200 messages/day, one account); $99/yr or $10/mo Pro; no per-message fee	No Meta approval. Your own number. Accounts unlimited on Pro	Real: bans are always possible. Reduced by shipped pacing profiles, 72h warming, per-number limits, duplicate guard, live risk scoring and auto-resume	Nothing for the core path. Configure pacing and consent-first batches. Free is live-only; Pro adds archived history, full-text search and the smart queue

How to run Evolution API in Docker

1. Provision a Linux host with Docker Start with a small Linux VPS and install Docker Engine plus the Compose plugin. Give it a static public IP and a domain you control, since the manager UI and webhooks both need a stable address.
2. Fetch the compose file and environment sample Clone the repository from github.com/EvolutionAPI/evolution-api and copy the environment sample to .env. Keep the file out of version control; it holds your credentials.
3. Set the required variables Configure database credentials, the API key, the server URL and a default webhook URL. Confirm the variable names against the docs for your major version, because names have changed between releases.
4. Start the stack Run docker compose up -d, then read the logs until migrations finish cleanly. If the API restarts in a loop, the database connection is almost always the cause.
5. Create an instance and link the number Open the manager frontend, create an instance, and scan the QR code from the phone that owns the number. The code expires quickly, so have the phone ready before you generate it.
6. Point webhooks and test one round trip Register your webhook per instance, send one message from a second phone, and confirm the event lands in your consumer. Add a broker in front before you rely on this in production, because without one dropped deliveries vanish silently.
7. Schedule backups Dump the database nightly and back up the media volume or object bucket. Session credentials live in the database, so a restore is what saves you from re-pairing every number after a failure.

Frequently asked questions

What is Evolution API in simple terms?

It is free, open-source software you run on your own server so other software can send and receive WhatsApp messages. It connects a number through the unofficial WhatsApp Web protocol and exposes HTTP endpoints and webhooks, so n8n, Chatwoot, Typebot or your own backend can automate that number. It is not made or endorsed by WhatsApp or Meta.

Is Evolution API official or made by Meta?

No. It is an independent open-source project, not affiliated with, endorsed by or approved by WhatsApp or Meta. It connects over the unofficial WhatsApp Web protocol rather than Meta's Cloud API, which is why summaries that call it an official API mislead on the point that matters most.

Is Evolution API free?

The software is free and open source. The real cost is infrastructure and engineering: a server, a PostgreSQL or MySQL database, optional Redis, broker and object storage, TLS, plus the time to build pacing, retries, storage and a safety layer yourself.

What is the difference between Evolution API v1 and v2?

V2 is the current major line. Between majors the project has changed endpoints, configuration keys and deployment shape, so follow the migration notes in the repository (github.com/EvolutionAPI/evolution-api) rather than a v1 tutorial. The releases page is the authoritative source for the version running today.

Do I need Docker to run Evolution API?

Docker is the standard and best-documented path, usually a Compose stack alongside a database. Running it without Docker is possible, but you then own the runtime, the dependencies and service supervision.

Which database does Evolution API need?

PostgreSQL or MySQL, per the repository's docker-compose file and environment sample. Redis is optional for caching, RabbitMQ or SQS is optional for events, and S3 or MinIO is optional for media storage.

Does Evolution API have anti-ban protection?

Nothing in its documented feature set is a safety layer: no session warming, no per-number rate limits, no pacing profiles, no duplicate-content guard, no live risk scoring, no auto-resume. Those can be built on top, but no tool can guarantee against bans.

Will my WhatsApp number get banned using Evolution API?

Bans are possible. Unofficial-protocol access sits outside WhatsApp's terms, and WhatsApp's Help Center warns that unofficial clients can lead to an account being banned (faq.whatsapp.com). Risk falls with consent-first messaging, a gradual ramp, per-number pacing and never sending identical text to many contacts. It is never zero.

How many messages a day can I send with Evolution API?

The project documents no daily cap and ships no sender discipline. The practical limit is WhatsApp's enforcement for your number plus whatever pacing you build. Meta documents messaging limits per business portfolio (Meta developer docs). For contrast, SocialMate Free is 200/day on one account; Pro starts at 500/day and scales to 5,000/day after 72 hours of warming.

Is Evolution API legal to use for a business number?

The software is lawful to download and run; the risk sits in the WhatsApp account. WhatsApp's Terms of Service restrict unauthorised or automated access and reserve the right to restrict or terminate accounts. This is not legal advice: if a business number carries revenue, get your own counsel and assume the account can be disabled.

Evolution API vs WAHA — which should I choose?

Both are self-hosted, unofficial REST APIs with no safety layer, so the decision turns on deployment shape and features rather than risk. WAHA advertises a lighter single-container setup with several engine options and a paid tier (per WAHA's own site); Evolution API leans on multi-instance management and a larger tutorial ecosystem. Neither removes WhatsApp's enforcement.

Can I run Evolution API on a Windows PC or spare laptop?

In practice yes, via Docker Desktop or WSL2, but that is not the documented production path and you inherit Docker's Windows quirks plus always-on power and network management. It is a fair question to ask, because a desktop machine on your own home connection is a different risk profile from a datacenter VPS.

Does Evolution API have an MCP server or an AI-agent interface?

Its documented surface is a REST API and webhooks; nothing published describes a native MCP server. SocialMate ships one, exposing 44 WhatsApp tools to Claude Desktop, Cursor and Claude Code, plus a first-class n8n community node whose every operation is callable as an AI-Agent tool once N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true is set. Neither generates replies; AI generation on SocialMate's side is coming soon.

Do I need Meta Business verification to use Evolution API?

No. There is no Meta approval, no business verification and no dedicated-number requirement, because it does not use Meta's Cloud API. Meta requires verification and a number not already on WhatsApp for production Cloud API use (Meta developer docs). That is the trade: no approval and no per-message meter, in exchange for operational work and real account risk.

Is SocialMate the same category as Evolution API?

Yes. Both are self-hosted WhatsApp automation that keeps data on infrastructure you control, neither is affiliated with Meta, and neither is the official WhatsApp Business API. The difference is packaging: Evolution API is a toolkit, SocialMate is a finished app with a shipped anti-ban engine, an inbox and a local API.