Evolution API, Baileys, and similar tools: when it pays off and when it becomes a problem
By José Pedro · Co-founder of CRPRO
Evolution API wraps Baileys, the unofficial library that speaks the WhatsApp Web protocol, in a REST layer. It pays off for a secondary number or an internal use case with someone on call. It becomes a problem the moment you hang the company's main number and revenue on it. See the real cost comparison and when each path holds up.
Evolution API is an unofficial HTTP layer on top of Baileys, the TypeScript library that speaks the WhatsApp Web protocol without going through Meta. It pays off when the number is secondary, the use case is internal or experimental, and there's someone around to fix it when it breaks. It becomes a problem when you hang the company's revenue on it: the cost doesn't arrive as a charged message, it arrives as engineering hours, a 3am on-call shift, and a number that can disappear with no warning at all.
What are Evolution API, Baileys, and the similar libraries?
They're three different layers, and a good chunk of the confusion comes from treating all three as one thing.
| Layer | What it is | How it connects |
|---|---|---|
| Baileys | A TypeScript library that implements WhatsApp Web's multi-device protocol | Direct WebSocket, no browser and no Chromium; pairing via QR code or a code |
| Evolution API | A service that wraps Baileys in REST: runs on Docker, creates instances, delivers events via webhook | Baileys underneath and, in recent versions, also Meta's official Cloud API — which makes it a provider router, not just a wrapper |
| whatsapp-web.js, Venom, WPPConnect | Libraries that automate a real Chromium browser | A real browser: closer to the official client's behavior, much more expensive in RAM |
None of them are official, none have a contract with Meta. All of them read the web client's protocol — your operation depends on a moving target that gives no notice before it moves.
What do these libraries actually solve?
It isn't nothing, and it's worth listing before talking about the hidden price:
| What you get | Why |
|---|---|
| R$0.00 per-message fee (no Meta charge on the QR code path, as of August 2026) | You pay for infrastructure, not fees |
| No template and no approval | No submitting copy and waiting for review to send a notice |
| No 24-hour window | You send whenever you want, to whoever you want, technically |
| Features the Cloud API doesn't have | Groups, status updates, "typing" presence, device history |
| The number stays on the phone | No migration: it's the same number, paired as one more device |
| Spins up in minutes | No Business Manager, no business verification, no BSP |
That last item is what moves the most people in practice. On the official API, a migrated number leaves the app — whoever depends on groups, status, or answering from their phone loses that.
Why does the session drop, and who reconnects the number?
The session is a set of cryptographic keys that needs to survive a restart, a deploy, and a container crash. The library's default stores this in a file; on an ephemeral container, that's guaranteed session loss. You'll want that state in Postgres or Redis, encrypted at rest — it's literally a customer's WhatsApp credential.
Reconnection isn't a rare error, it's routine: a phone with no internet for too long, an accidental logout, a protocol change on Meta's side. And when it drops, someone needs to scan a new QR code. A QR code needs a person, not a script — there's no way to automate scanning a code that appears on your screen and needs to be pointed at the right phone. That's the first question that kills a project on paper: who does this at 3am on a Sunday?
A pinned version against a moving target
When WhatsApp changes something, your library breaks until someone on GitHub commits a fix. There's no date, no SLA, no ticket to open. The fix arrives mandatory and unplanned — and along the way come the familiar symptoms of anyone running this: media that won't download, a message stuck on "pending," an encryption session out of sync for one specific contact.
The available defense is procedural, not contractual: pin the library version, keep a canary environment that gets the upgrade before production, and have an exit route to another provider designed before you need it.
Does the official API eliminate ban risk?
No. This is the comparison both sides get wrong. Meta keeps the field waba_ban_state in the account_update webhook, with values DISABLE, SCHEDULE_FOR_DISABLE, and REINSTATE, and error 368 exists precisely for a restricted account. A number on the official API can be banned — anyone promising immunity is selling something.
What changes isn't whether the risk exists, it's how much of it you can see. On the QR code path, the penalty arrives with no prior metric, no warning, and no process with a deadline. On the official API, there's continuous measurement and notification before shutdown. It's the difference between losing the number by surprise and watching the indicator turn yellow with time to react.
What the official API gives you in exchange: warning, measurement, and appeal
| QR code / Baileys | Official API | |
|---|---|---|
| Warning before the penalty | None | Email notification before shutdown |
| Quality measurement | Doesn't exist for you | Green/yellow/red quality rating per number, calculated on a weighted basis over the last 7 days (criteria documented by Meta, checked as of August 2026), visible in WhatsApp Manager and via the API |
| Escalation | Straight to shutdown | Gradual restriction before shutdown |
| Appeal | A generic form, no deadline | A formal appeal through Business Manager |
Add a technical detail almost nobody notices: on the official API, sending outside the 24-hour window is impossible — the call returns error 131047 and only a template reopens the conversation (rule in effect as of August 2026). The system protects you from yourself. With Baileys, nothing stops the send: the guardrail Meta would have implemented becomes your code's responsibility. And an unofficial library isn't the same as a modified app — GB WhatsApp and WhatsApp Plus explicitly violate the Terms —, but it isn't endorsed by anyone either.
Infrastructure, state, and observability: what changes on your end
A Baileys instance is stateful, which knocks down the comfortable assumption of spinning up replicas behind a load balancer: each number lives in a specific process, and routing needs to know that. In practice you end up with:
- a healthcheck that actually tests the connection, not an HTTP
200 OK; - a sending queue with backoff and jitter, never a
forloop with a fixedsleep; - an idempotent webhook keyed by message id, because redelivery happens;
- an alert on the disconnection event, with someone on call on the other end;
- a backup of the auth state with a tested restore — an untested restore is an imaginary backup.
And LGPD: syncing pulls the device's history into your database, and you've become the controller of personal data you might not have planned to store.
What does it actually cost to run Baileys?
The honest comparison isn't "R$0.00 versus Meta's fee." It's (engineering hours per month × your cost per hour) + infrastructure + downtime cost × probability against the official API's bill under your real message mix.
If you have a software team, that first term is small and the math usually favors QR code. If you hired a freelancer to spin up the Docker container and they left, the term is large and lands concentrated on the worst possible day — usually a Friday during a campaign. The classic mistake is measuring only the deployment cost, which is low in any scenario, and ignoring the maintenance cost, which repeats every month.
When does it pay off to use Evolution API or Baileys?
- Prototyping and validation. Spending weeks on business verification only to find out the flow was bad is the worse deal.
- Internal use. System alerts, a bot in an internal group, deploy notifications. Nobody's going to report you, the number is secondary, a drop is annoying but doesn't cost a sale.
- What the Cloud API doesn't do. Groups and status don't exist on the official API. If that's your use case, there's no choice to make.
- High-volume inbound support with a technical team in-house. This argument got stronger: since October 1, 2026, Meta charges per message for service messages and utility templates sent inside the 24-hour window. The service-message rate is in Meta's current price table, and anyone with a high message count per conversation should redo the math with it before deciding. There's a whole post on it in when not to migrate to the official API.
When does Evolution API become a problem?
- It's the company's main number. A ban with no warning on the number that's on the website, the business card, and Google is a business-continuity event, not an IT incident.
- Outbound marketing at scale. The worst-case scenario. Bulk sending to a cold list through Baileys is the shortest path to losing the number, with no warning and no appeal. If the goal is a campaign, read this first — the policy requires opt-in.
- Nobody's on call. If the answer to "who scans the QR code at 3am on a Sunday" is silence, the architecture has already failed on paper.
- A contract or an audit requires an official channel. Some sectors don't accept anything outside the official API, and no technical argument beats that clause.
You can use both — and that's usually the right answer
The choice doesn't need to be exclusive per company, only per number. One number on the official API for campaigns with opt-in, an approved template, and a monitored quality rating. One number on QR code for the internal team, for groups, for whatever the official one doesn't cover. And if QR code is going to be your front line, keep a warmed-up backup number and a data model that lets you swap providers without rewriting the CRM.
CRPRO operates in both modes for exactly this reason — the official API through a BSP and a QR code connection, with the same multi-agent support and the same history on top. If you're designing this architecture right now, you can test both paths before choosing.
Frequently Asked Questions
Is Evolution API allowed by WhatsApp?
It's neither official nor certified. It's an unauthorized implementation of the WhatsApp Web protocol, in the same family as Baileys, Venom, and WPPConnect. It works, it's widely used, and it has no endorsement from Meta — which means you operate with no contract and no support on the other end.
Does using Evolution API get the number banned?
The tool itself isn't what triggers a ban; behavior is. But on QR code, the penalty arrives with no advance warning, no visible quality rating, and no appeal with a deadline. On the official API, a ban is also possible — the waba_ban_state field and error 368 exist for exactly that — but it comes with a warning, measurement, and process.
Is Evolution API cheaper than the official API?
Per message, yes: you don't pay Meta's fee. In total, it depends on what your time is worth. Add up infrastructure, session maintenance, unplanned upgrades, and the expected cost of downtime. If you have a technical team, it usually wins. If you don't, the savings show up on the wrong invoice.
What's the difference between Baileys and whatsapp-web.js?
Baileys speaks the protocol directly over WebSocket, with no browser — lighter and faster. whatsapp-web.js (and Venom, and WPPConnect) automates a real Chromium browser — heavier on memory, but closer to the official client's behavior. Both break when WhatsApp changes something; what changes is the type of break.
Can I use Evolution API and the official API on the same number?
Not at the same time. A number migrated to the official API leaves the app, and it's the Cloud API that responds for it from then on. The workable setup is having different numbers for different purposes, under the same CRM.
How long does it take for the quality rating to recover?
The indicator is recalculated over the last 7 days on a weighted basis, so stopping the practice that triggered user blocks doesn't bring back green the same day: it takes a few days of better behavior before the calculation window reflects it. That's why the indicator works as an early warning, not an immediate-reaction dashboard.