GLOSSARY

What is a WABA?

A WhatsApp Business Account (WABA) is the container object inside Meta Business Manager that owns your WhatsApp business phone numbers, your message templates, and the quality and messaging-limit state attached to them. It is identified by a numeric WABA ID and it is the object your app subscribes to in order to receive WhatsApp webhooks.

Try Pinlyx free See live demo

Free forever plan · No credit card required · Cancel anytime

Quick definition

In a single sentence: the WABA is the folder, the phone numbers are the files, and the templates are shared by everything in the folder.

What it means

A WhatsApp Business Account, almost always written as WABA, is not an account you log into. It is a record in Meta's graph. When you open WhatsApp Manager and see a list of phone numbers, a template library and a set of quality indicators, you are looking at the contents of exactly one WABA.

The confusion that costs teams the most time is the name. There are three different things called some variation of "WhatsApp business account":

The WhatsApp Business app, a free mobile app for one owner and one number, with no API surface at all.
The WhatsApp Business Platform, the API product formerly marketed as the WhatsApp Business API.
The WABA, the object inside the platform that this page is about.

Only the third one has an ID, and that ID is what every Graph API call about templates and account state is addressed to.

Where a WABA sits in the object hierarchy

Four objects stack on top of each other, and knowing which layer an error belongs to is most of WhatsApp Platform debugging. A template rejection is a WABA-level event. A quality drop is a phone-number-level event. A missing permission is an app-level event. Blaming the wrong layer is the reason so many teams "reconnect the integration" and see no change.

The WABA layer specifically owns:

Message templates. Created at /{waba-id}/message_templates, approved by Meta, and usable by every phone number in the same WABA.
Phone number registration. Read them at /{waba-id}/phone_numbers. A number belongs to exactly one WABA at a time.
Webhook subscriptions. /{waba-id}/subscribed_apps decides which Meta app receives events for this account.
Account review and restriction state. Meta reviews a WABA when it is created and again whenever a violation is reported.
Analytics. Conversation and message counts are aggregated at the WABA level, which is also where billing attribution starts.

Getting a WABA: the two routes

Embedded Signup is the flow where your product opens a Meta-hosted popup, the customer logs in with their own Facebook credentials, picks or creates a Business Portfolio, creates the WABA, adds a phone number and verifies it by SMS or voice call. At the end your app receives an authorisation code you exchange for a token. The customer owns the WABA; you are granted access to it. This is the correct architecture for any SaaS product with more than one customer.

Manual creation is the flow where you build the WABA yourself in Business Manager and add a number by hand. It is fine for your own company's number and it is what most teams use for their first test, but it does not scale to customers and it leaves the WABA owned by whoever clicked the buttons.

One rule survives both routes: a phone number that is currently active in the WhatsApp Business app or in consumer WhatsApp cannot be added to a WABA until it is deleted from that app first. The account deletion has to happen on the device, and the chat history goes with it. Teams that skip this step get a verification code that never arrives and blame the carrier.

Why it matters

The WABA is the blast radius of a compliance mistake. Quality rating is per number, which feels reassuring until you notice that template approval, template pausing and account restriction are per WABA. One marketing template that Meta reads as a scam can put the whole account into review, and every brand you put in that account stops being able to ship new templates while the review runs.

That single fact should drive your architecture. If you run multiple brands, or you send marketing for one line of business and critical service notifications for another, splitting them into separate WABAs is not paranoia. It is the only isolation boundary the platform gives you.

The second reason it matters is portability. A WABA owned by your Business Portfolio can be shared with a provider and later unshared. A WABA owned by a provider cannot be taken with you, and the template library you spent months getting approved does not transfer. Ask who owns the WABA before you sign anything.

Real-world examples

An agency onboarding 40 clients. Each client gets its own WABA created through Embedded Signup under the client's own Business Portfolio. The agency's Meta app is subscribed to all 40. A restriction on client 12 has no effect on the other 39.
A clinic group with five locations. One WABA, five phone numbers, one shared template library for appointment reminders. Reminders are utility templates, quality stays high, and each location's quality rating is visible separately so a receptionist who ignores messages is easy to spot.
An online retailer running promotions. Two WABAs on purpose: one for order and shipping notifications, one for marketing blasts. When a promotion earns enough blocks to trigger a review, order notifications keep flowing.
A team that lost its webhooks. Everything looked correct in the app dashboard, but GET /{waba-id}/subscribed_apps returned an empty array. The Meta app had been recreated during a refactor and nobody re-subscribed it. Inbound messages had been dropped for nine days.

Common mistakes

Confusing the WABA ID with the phone number ID. Templates are addressed to the WABA. Messages are addressed to the phone number. Swapping them produces a (#100) Unsupported get request or a permission error that tells you nothing useful.
Putting every brand in one WABA. Convenient until the first restriction, at which point every brand is frozen at once.
Letting a provider own the WABA. The template library, the verified display name and the quality history all stay behind when you leave.
Assuming account review is a one-time gate. Meta re-reviews on reports. An account that passed review in January can be restricted in June with no configuration change on your side.
Ignoring the account_update webhook. It is how Meta tells you the WABA was restricted, the display name was approved, or a policy decision was made. Teams that do not handle it find out from a customer complaint instead.

Related concepts

Phone Number ID: the child object that actually sends messages.
Message template: owned by the WABA and shared by every number in it.
Quality rating: the per-number signal that decides whether the WABA stays healthy.
Messaging limit: the tier that business verification on the parent portfolio unlocks.
Webhook: delivered to the app subscribed to the WABA, not to the phone number.
Omnichannel CRM: where WABA conversations land next to Telegram, email and Instagram.

How Pinlyx handles it

Pinlyx connects to a WABA through Embedded Signup, so the account stays owned by your Business Portfolio and you can disconnect without losing templates. Each connected WABA shows its numbers, per-number quality rating and messaging tier on one screen, and the account_update and message_template_status_update webhooks are surfaced as alerts rather than buried in logs. Inbound messages from every number in the WABA land in the same shared inbox your Telegram, X and email conversations use, so an agent does not have to know which container a message came from. See WhatsApp CRM for the full picture.

Cheat sheet · which layer owns what

Four objects, four completely different failure modes.

Read an error against this table before you touch any configuration.

Layer	What it owns	ID field	Typical failure
Meta Business Portfolio	The legal business entity in Meta Business Manager. Holds verification status, payment methods and people.	`business_id`	Business verification is incomplete, so the WABA below it can never leave the starter messaging tier.
WhatsApp Business Account (WABA)	The WhatsApp-specific container. Owns templates, phone numbers, the account review status and webhook subscriptions.	`waba_id`	A policy violation restricts the whole WABA, which pauses template creation across every number under it.
Business phone number	One registered WhatsApp sender. Carries its own quality rating, messaging limit and display name.	`phone_number_id`	The number is flagged, so one bad sender drags a campaign down without touching the sibling numbers.
Meta app	The developer app that holds the access token and receives webhooks after being subscribed to the WABA.	`app_id`	The app was never added to /{waba-id}/subscribed_apps, so inbound messages silently go nowhere.

The three calls that prove a WABA is wired up

Verify the account before you debug the messages.

# 1. Which numbers does this WABA own, and how healthy are they?
GET /v22.0/{waba-id}/phone_numbers
    ?fields=id,display_phone_number,verified_name,quality_rating,code_verification_status

{
  "data": [
    {
      "id": "106540352242922",
      "display_phone_number": "+90 555 000 00 00",
      "verified_name": "Acme Clinics",
      "quality_rating": "GREEN",
      "code_verification_status": "VERIFIED"
    }
  ]
}

# 2. Is any app actually subscribed? An empty array means zero webhooks.
GET /v22.0/{waba-id}/subscribed_apps

{ "data": [] }          <- the silent killer

# 3. Fix it. This is the call almost everyone forgets.
POST /v22.0/{waba-id}/subscribed_apps

{ "success": true }

WABA scoped

Templates, subscriptions, account review, analytics.

Number scoped

Quality rating, messaging limit, display name, sending.

Portfolio scoped

Business verification, payment method, people and roles.

Watch out for

The WABA is your only isolation boundary.

Quality is measured per number, which makes teams think a bad sender is contained. It is not. Template review, template pausing and account restriction all happen at the WABA level, so a single aggressive marketing template can freeze template creation for every brand and every number sharing that account. If two message streams must never take each other down, they belong in two WABAs, and the decision is much cheaper to make on day one than after the first restriction.

WABA: FAQ

The questions every team asks in the first week of a WhatsApp Business Platform integration.

They are unrelated products that share a name. The WhatsApp Business app is a free phone app for a single small business, with no API, no templates and no programmatic access. A WABA is an object in Meta Business Manager that exists so software can send and receive messages through the WhatsApp Business Platform. A phone number can be attached to one or the other, never both at once, and moving a number from the app to a WABA deletes the chat history stored on the device.

You can create a WABA and send messages before verification, but you are capped in the starter tier and limited on how many numbers you can add. Meta Business Verification, where you upload documents proving the legal entity, is what unlocks higher messaging limits and the ability to apply for an Official Business Account display badge. Verification is done at the Business Portfolio level, not the WABA level, so one verification covers every WABA under that portfolio.

Meta publishes a per-WABA number cap that has moved over the years and depends on verification status, so treat any specific figure as subject to Meta's current policy. What matters architecturally is that templates are shared across every number in the WABA, while quality rating and messaging limit are tracked per number. Group numbers into one WABA when they should share a template library, and split them when a compliance failure on one brand must not be able to restrict another.

A BSP is a Meta partner that can create and host WABAs on your behalf, usually adding its own dashboard, per-message markup and support. Since Cloud API is hosted by Meta and free at the infrastructure level, a direct integration is entirely possible without a BSP. The practical reasons teams still use one are onboarding help, consolidated billing, and access to features a partner has early. If you own the WABA yourself through Embedded Signup, you keep the ability to change providers without losing your template library.

Almost always because the app is not subscribed to the WABA. Creating a Meta app, configuring a callback URL and setting the verify token is only half the job. You must also POST to /{waba-id}/subscribed_apps so that this specific WABA delivers events to this specific app, and you must tick the individual webhook fields, most importantly messages, message_template_status_update and phone_number_quality_update. A GET on the same edge tells you which apps are actually subscribed.

Restriction is a WABA-level state, separate from a phone number being flagged. Depending on the severity you may lose the ability to create new templates, lose the ability to send business-initiated messages, or lose messaging altogether. Meta surfaces the state in WhatsApp Manager and through the account_update webhook. You appeal from inside the Business Support Home. The recovery path is the same in every case: find the policy that was violated, prove it is fixed, and reduce the volume that produced the negative feedback in the first place.

Keep reading

Phone Number ID

The child object that every send request is addressed to.

Message template

Owned by the WABA, shared by every number under it.

Quality rating

The per-number health signal Meta scores you on.

Messaging limit

How many unique customers you can start a conversation with.

Webhook

Delivered to the app subscribed to the WABA.

WhatsApp CRM

Run WABA conversations inside a shared team inbox.

Ready to ship

Connect your WABA. Keep the keys.

Pinlyx connects through Embedded Signup so the WhatsApp Business Account stays yours, with per-number quality and template status surfaced as alerts.

Start free Talk to sales

Free forever plan · GDPR-ready · No credit card required