WhatsApp Cloud API vs Unofficial Libraries: Which Should You Use?

WhatsApp Cloud API vs an unofficial library: two very different paths

If you want to send or receive WhatsApp messages from code, you face a fork in the road. One path is the official WhatsApp Business Cloud API, hosted by Meta on the WhatsApp Business Platform. The other is a family of unofficial open-source libraries — most prominently Baileys and whatsapp-web.js — that reverse-engineer the WhatsApp Web protocol and drive a regular personal account. They look interchangeable in a quick demo, but they sit on opposite sides of a line: one is a sanctioned, paid, compliant channel; the other is a free-but-prohibited workaround that WhatsApp actively detects and bans.

This guide compares them honestly. We will look at cost (including the major pricing change Meta shipped on July 1, 2025), onboarding and verification, the 24-hour customer service window and message templates, ban risk, scalability, and compliance — then give a clear recommendation for which to choose based on what you are actually building. The goal is not to dismiss either option but to help you pick the right tool without nasty surprises.

The official WhatsApp Business Cloud API

The Cloud API is a REST API exposed through Meta's Graph API. You POST messages to an endpoint like graph.facebook.com/<version>/<phone-number-id>/messages and Meta handles the rest. Meta hosts it for free. The older self-hosted On-Premises API reached end-of-life on October 23, 2025 (Meta first announced its deprecation back in October 2023), so the Cloud API is now the only path for new and migrating integrations. You can integrate directly with Meta or through a Business Solution Provider (BSP) such as Twilio, Infobip, 360dialog, or Vonage, which add tooling and support on top — usually at a markup.

Onboarding is the price of legitimacy. You need a Meta Business Portfolio, a WhatsApp Business Account (WABA), and a phone number that is not currently active on the consumer WhatsApp or WhatsApp Business app. Setup typically runs through Embedded Signup. Completing Business Verification — submitting legal documents to Meta — unlocks higher messaging limits and display-name benefits. It is more friction than scanning a QR code, but in return you get deliverability, an SLA-backed channel, and protection from bans.

# Graph API version below is illustrative — use the latest stable version
# Meta publishes (e.g. v23.0). Pin a version explicitly; do not omit it.
curl -X POST \
  'https://graph.facebook.com/v23.0/<PHONE_NUMBER_ID>/messages' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "template",
    "template": {
      "name": "order_confirmation",
      "language": { "code": "en_US" }
    }
  }'

The 24-hour window and message templates

The Cloud API's central rule is the 24-hour customer service window. When a user messages your business, a window opens; it lasts 24 hours from that user's most recent inbound message and resets every time they reply. Inside the window you may send free-form messages in any format — text, media, interactive buttons. Outside the window you may only send pre-approved message templates.

Templates are submitted to Meta for review. Approval is often near-instant for verified businesses and can take up to about 24 hours otherwise. Templates fall into three categories that drive billing: Marketing, Utility, and Authentication. This template system is what keeps the channel low-spam — and it is the single biggest behavioural difference from unofficial libraries, where you can send anything to anyone with no review (and no protection).

2025 pricing: per-message, not per-conversation

This is where many older articles are wrong. On July 1, 2025, Meta moved from conversation-based pricing to per-message pricing. You are now billed per delivered template message, not per 24-hour conversation, and the old 'first 1,000 conversations per month free' tier no longer applies under the new model. Non-template service messages — your replies inside an open window — are free.

There are three paid template categories. Crucially, Utility templates are free when delivered inside an open 24-hour customer service window, and charged only when sent outside it. Marketing and Authentication templates are charged regardless of the window. Rates are set per recipient country code and vary widely — as of 2025, Marketing rates in markets like Brazil sit at the higher end, while India is among the cheapest — and volume-based discount tiers apply to utility and authentication traffic.

To budget at all, you need rough numbers — but treat these as directional, not authoritative. As of 2025, per-message rates for charged categories commonly land somewhere between roughly US$0.005 and US$0.10 depending on the recipient's country and the template category, with Marketing typically the most expensive tier and Authentication/Utility cheaper, especially with volume discounts. These figures move; price a real campaign against Meta's official rate card for your target countries before committing.

Unofficial libraries: Baileys and whatsapp-web.js

Unofficial libraries speak the WhatsApp Web protocol on behalf of a personal account linked through the multi-device 'linked devices' feature. They are free, install in minutes, and let you send free-form messages immediately with no templates, no window, and no verification. That convenience is exactly why they are popular for prototypes — and exactly why they are risky for production.

Baileys (repo WhiskeySockets/Baileys, MIT licensed, maintained by the WhiskeySockets org) is a TypeScript library that talks the WhatsApp Web WebSocket protocol directly. It uses no Chromium or Puppeteer, so it is light on RAM and fast. The v7 line — currently shipping as release candidates rather than a stable GA release — introduces breaking changes with a migration guide; login is via QR code or pairing code. The npm package is now simply baileys (the legacy scope @whiskeysockets/baileys still publishes the same project).

whatsapp-web.js (repo wwebjs/whatsapp-web.js, originally by Pedro S. Lopez, Apache-2.0) takes a different approach: it drives a real headless Chromium running WhatsApp Web via Puppeteer. It is one of the most popular WhatsApp Web libraries and its API is approachable, but it is heavier, needs Node 18+, and is more brittle when WhatsApp changes its web UI. Both projects carry explicit disclaimers that they are not affiliated with WhatsApp and that you may be blocked.

import makeWASocket, { useMultiFileAuthState } from 'baileys'

const { state, saveCreds } = await useMultiFileAuthState('auth')
const sock = makeWASocket({ auth: state })

sock.ev.on('creds.update', saveCreds)
sock.ev.on('messages.upsert', async ({ messages }) => {
  const msg = messages[0]
  if (!msg.key.fromMe && msg.message) {
    await sock.sendMessage(msg.key.remoteJid, { text: 'Hello from Baileys' })
  }
})

Ban risk and compliance: the honest part

WhatsApp's Terms of Service prohibit unofficial clients and automated or bulk messaging. WhatsApp's own help center explains that using unauthorised apps can get your account banned — and in practice bans are often permanent and arrive without warning. The maintainers of both libraries say the same thing in their READMEs: they are not affiliated with WhatsApp, and they discourage bulk, automated, or stalkerware-style use. There is no SLA, no support, and no compliance guarantee.

Risk scales with how 'commercial' your behaviour looks. A brand-new number, high send volume, cold outreach to people who never messaged you, and identical bulk content are the strongest triggers. A low-traffic personal automation on an aged number is less likely to be flagged — but 'less likely' is not 'safe.' If losing the number would hurt your business, do not put it on an unofficial client.

The Cloud API, by contrast, is the sanctioned channel. It is governed by the WhatsApp Business Messaging Policy and Commerce Policy, and quality matters: a low quality rating can throttle your messaging limits or pause specific templates. But you are not at risk of a surprise account ban for simply using the API as intended — compliance is built into the model rather than fought against it.

Scalability and messaging limits

The Cloud API enforces messaging limits on business-initiated template messages. Since the October 7, 2025 change, these limits apply at the Business Portfolio level rather than per phone number — so the starting tier of 250 unique recipients per rolling 24 hours is itself shared across your whole portfolio, not granted afresh to each number you add. From that 250 floor, the limit rises to 1,000 after Business Verification, then 10,000, 100,000, and eventually unlimited as your volume and quality rating prove out. Service messages (replies inside the window) are unlimited.

Unofficial libraries have no formal limits — but that is a trap, not a feature. There is no enforced ceiling because there is no sanctioned channel; the practical ceiling is 'how much can you send before WhatsApp's spam detection bans you.' For genuine scale, the Cloud API's predictable, published tiers are far more useful than an unofficial library's unbounded-until-banned behaviour.

Which should you actually use?

Choose the WhatsApp Business Cloud API for anything production, commercial, or high-volume: customer support at scale, OTPs and authentication, transactional alerts, and compliant marketing notifications. You pay per template plus any BSP markup, and you accept onboarding friction — in exchange for reliability, deliverability, support, and protection from bans. For any business that depends on WhatsApp, this is the only responsible choice.

Choose an unofficial library only for hobby projects, prototypes, internal tooling, or personal automation on a number you can afford to lose. Pick Baileys when you want a lightweight, browser-free WebSocket client; pick whatsapp-web.js when you prefer a simple, batteries-included API and don't mind running headless Chromium. Just go in clear-eyed: it is free but ToS-violating, with real legal and operational risk and zero guarantees. It is not a drop-in replacement for the Cloud API in a business setting.

There is also a third, complementary category worth knowing. If your real need is simply to verify whether numbers are on WhatsApp and enrich them with public profile data before you message them, you don't need a full messaging client at all. A read-only profile lookup checks registration and returns public details such as the profile picture, display name, about text, and business-account flag — without logging in as a user or risking a messaging ban. Clean your list with one of those, then message the valid contacts compliantly through the Cloud API.

Frequently asked questions