Baileys in practice: what we learned running an unofficial cluster

Baileys is a library that automates WhatsApp Web: it opens a session as though it were a paired browser and sends messages through it. It is free, it is up in minutes and it asks approval for nothing. It also breaches WhatsApp’s terms, and the session it maintains is the single point of failure of anything built on top.

This is not a review: it is what we learned running a cluster of these instances in production, with paying customers, before migrating them to the Cloud API.

What works well

Worth starting with what is true and usually omitted by whoever is selling the alternative:

• It is up in minutes. Install, scan the QR code, send.
• It charges nothing per message. For high notification volume the cost difference is orders of magnitude.
• It requires no template approval. You write and you send.
• It does things the official API does not — groups, mainly.

For a prototype, an internal tool or low volume on a disposable number, it is hard to argue for anything else.

The failure that does not show up in monitoring

A WhatsApp Web session does not survive a reboot. That is in the documentation of every project of this kind and everybody knows it — in theory.

On our cluster, two servers restarted on the same day. That day, 41 instances went into a reconnecting state and never came back on their own. All 41 carried the same last-updated date. We found out weeks later, when we measured the cluster to plan the migration.

The service stayed up, answering status requests, consuming resources and reporting health. It just had no session. Silent failure is worse than an outage: somebody notices an outage.

It is the kind of problem generic monitoring does not catch. "The process is running" and "the endpoint returns 200" both remained true. The right question — "does this instance have a valid session right now?" — has to be asked explicitly, instance by instance.

What breaks, by frequency

1. Server reboots. The session dies and does not return without manual reconnection or automation built for it.
2. App updates. The library chases the protocol, and there is a window where it simply does not work.
3. Expired pairing. Sessions age out and drop with no clear event.
4. Number blocks. No warning, no timeline, no predictable appeal.

The first three are operational and can be mitigated with work. The fourth cannot: it follows from automating WhatsApp Web, which is what the library does by definition.

The cost that was not in the spreadsheet

The calculation that usually justifies the choice compares Meta’s per-message fee against zero. It leaves out three lines:

• Operations — servers, reconnections, someone on call to restore sessions, purpose-built monitoring.
• Loss from silent failure — messages the store believes it sent and did not.
• Replacing the number — when the number that falls is the same one support uses, the cost is not the number: it is the customer who cannot reach you.

It was the sum of those three, not the fee, that led us to shut the cluster down and move customers to the Cloud API.

When it still makes sense

This is not a condemnation. The library remains the right choice in some cases:

• A proof of concept that will live for two weeks.
• Internal automation, on a number that is not the business.
• An operation that depends on groups, which the official API does not serve at all.
• High notification volume where the official API arithmetic demonstrably does not close.

What changes the answer is one question: if this number stops working tomorrow, what happens to the company?

If the decision is to migrate

Migration keeps the number, provided it is not blocked and the old session is ended first. What does not migrate is the copy: on the official API, a message that starts with you is an approved template.

The walkthrough is in migrating to the official WhatsApp API, and the criterion-by-criterion comparison in official vs unofficial WhatsApp API.

Frequently asked questions

Is Baileys safe?

The code is mature and maintained. The risk is not in it: it is in the method, because automating WhatsApp Web breaches the terms and exposes the number to a block.

Can I use Baileys without getting banned?

You can lower the probability — low volume, opt-in, no bulk sending. You cannot eliminate it, because the breach is the usage, not the content.

What is the difference between Baileys and the Cloud API?

Baileys automates WhatsApp Web through reverse engineering; the Cloud API is Meta’s official interface, hosted by them, where automating is the intended use and every initiated template is billed.

Can the Baileys session be persisted?

Credentials can be saved and reloaded, which helps. It does not remove the problem: the session still expires, still breaks on app updates and still needs supervised reconnection.