WhatsApp Business API guide for sales teams (2026)

The WhatsApp Business Platform is five objects, two independent quality ladders, one 24-hour window and roughly eight error codes that account for nearly every failure a sales team meets. Get the object model right and the rest is configuration. Get it wrong and you will spend weeks debugging symptoms — a template that will not send, a number that stops climbing, a message that reports success and never arrives — that all trace back to a relationship between two objects nobody drew on a whiteboard.

The five objects you have to keep straight

Almost every WhatsApp integration problem is a confusion between two of these, so name them once, precisely.

• The Meta Business portfolio is the top-level account that owns everything else and holds verification status. Business verification is one of the scaling paths out of the lowest messaging tier, so this object has performance consequences, not just administrative ones.
• The WhatsApp Business Account (WABA) sits inside the portfolio and is the container for phone numbers and message templates. Templates belong to the WABA, not to a number, which is why every number under one WABA shares a template library.
• The business phone number is the sending identity. It carries its own quality rating and its own messaging tier, which is why senders are configured and monitored per number rather than per account. Two numbers under the same WABA can be in completely different health.
• The message template carries a category, a language, a body with positional variables, its own quality rating and its own approval status. A template is approved per language: the same name in a different locale is a different approval.
• The app and its credentials — the Meta app, the system user and the access token — are what actually authenticate the API call. Webhook subscriptions attach here and at the WABA level, which matters because some events are WABA-scoped and will not arrive on a subscription you set up for a phone number.

Two of these carry quality ratings and they move independently. That is the single most common source of confusion and it deserves its own section below.

Cloud API, a provider, or both: what you are actually choosing

As of 2026 there is one API. Meta's On-Premises API sunset documentation states that the final supported version of the On-Premises API client expired on 23 October 2025 and that it can no longer be used to send messages to WhatsApp users, and that business phone numbers can only be registered for use with the Cloud API. Any proposal that still offers an on-premises client is describing something that does not send.

The real choice is direct integration versus a Business Solution Provider.

Direct means you own the Meta app, the system user token, the webhook endpoint and the template registry, and you are billed by Meta for messaging. You get full control and full responsibility, including token rotation, webhook signature verification and template submission.

Through a provider means the provider hosts the integration and provisions the number, and you consume their API. You get a shorter path to a working number and a support contact, and you inherit their rate limits, their template tooling and their pricing margin.

What does not change either way: the messaging limits, the template approval rules, the customer service window, the per-user marketing limits and every error code below. Those are Meta's, and no provider can widen them. If you are evaluating this decision, connecting a number through the Meta WhatsApp Cloud API directly is worth pricing against a provider before committing, because the difference is mostly operational rather than functional.

Messaging tiers, and how a number climbs them

The messaging limit is the number of unique WhatsApp users you may message in a rolling 24-hour period. Meta's messaging limits documentation lists the tiers as 250, 2,000, 10,000, 100,000 and unlimited.

Every new business number starts at 250. Two mechanisms move it:

1. A scaling path, used to leave 250. Meta describes completing one requirement — business verification, or delivering 2,000 messages outside customer service windows to unique WhatsApp user phone numbers within a 30-day moving period, using templates with a high quality rating.
2. Automatic escalation above 2,000, which requires two conditions at once: maintaining high-quality messaging, and using at least half your current limit within seven days. Meta says upgrades occur within six hours of qualifying.

Read that second mechanism carefully, because it has a counter-intuitive consequence. A number that stays well under its limit will not climb. Teams that cautiously send 400 messages a day on a 2,000 tier are not being safe, they are being stuck. The path up requires volume and quality together, which is why the tier is a poor proxy for how much you should send and a good proxy for whether Meta currently trusts you.

The tier is also a ceiling worth respecting in software rather than in a spreadsheet. Autocloz records the messaging tier Meta reports through the phone-number quality webhook and bounds the sender's configured daily limit by it, treating the tier as a maximum and never as a minimum: an operator who set 100 on a number Meta placed at 2,000 meant 100.

Template quality is a separate ladder from number quality

This is the distinction that costs teams the most time. A number has a quality rating. Each template has its own. They are computed separately and they fail separately.

Template quality is shown as Active - High quality, Active - Medium quality or Active - Low quality in WhatsApp Manager, and as a quality_score over the API where RED is the lowest band. Meta attributes a fall to "recurring negative feedback from customers, or low read-rates" — and the inclusion of low read rates is the part people miss. A template nobody reports but nobody opens is on the same path as one people complain about.

The pause ladder is published and short: 3 hours on the first instance, 6 hours on the second, and disabled on the third. After a pause expires the template unpauses itself and returns to active. The third instance is permanent.

The practical rules that follow:

• Retire a template at medium quality, not at the first pause. Medium is the warning; the pause is the consequence.
• A paused template does not take the number down. Another approved template on the same sender keeps working, which is why having two live templates per use case is worth the submission effort.
• Read rate is a controllable input. It is mostly a function of who you sent to and how often, not of the wording.

What Meta charges for since 1 July 2025

The pricing model changed and a great deal of published guidance is still describing the old one.

Meta's pricing documentation states that effective 1 July 2025, Meta charges on a per-message basis, replacing the earlier conversation-based model. The consequences worth knowing:

• Marketing and authentication templates are charged per message, at rates that vary by country.
• Utility templates delivered inside an open customer service window are free.
• All non-template messages sent inside an open customer service window are free.
• Messages inside a free entry point window are free for 72 hours. That window opens when a user contacts you through a Click to WhatsApp ad or a Facebook Page call-to-action button.

Put together, those four bullets describe an incentive: Meta charges you to interrupt and does not charge you to converse. A programme designed around conversations the customer starts is dramatically cheaper than one designed around outbound templates, and it is also the one Meta's quality systems reward. The go-to-market side of that trade — where the opt-in comes from and what the first template should ask for is the companion to this architecture.

The failure codes a sales team will actually meet

Eight codes cover most of it. Meta's own descriptions, and what each one means in practice:

• 131047 — "More than 24 hours have passed since the recipient last replied to the sender number." The customer service window closed. Re-issue as an approved template; free-form will keep failing until they message you.
• 131049 — "This message was not delivered to maintain healthy ecosystem engagement." The per-user marketing limit. Meta publishes no number for it and directs you to wait 24 hours or more before retrying.
• 131048 — "Message failed to send because there are restrictions on how many messages can be sent from this phone number." A number-level restriction; check the quality status in WhatsApp Manager rather than the template.
• 131026 — "Unable to deliver message." Meta lists the causes as the recipient not being a WhatsApp user, not having accepted the terms, or running an outdated version. This is a property of the recipient, so retrying is pointless and the row should be suppressed rather than requeued.
• 130429 — "Cloud API message throughput has been reached." A rate limit rather than a policy refusal. Slow down and retry.
• 132000 — "The number of variable parameter values included in the request did not match the number of variable parameters defined." A template-level fault that fails identically for every recipient.
• 132001 — "The template does not exist in the specified language or the template has not been approved." Usually a locale mismatch: en and en_US are different approvals.
• 133010 — "Phone number not registered on the WhatsApp Business Platform." A provisioning step was missed.

The classification that matters operationally is which of these are facts about the recipient (131026, and 131049 for that person for a while) versus facts about your sender or template (131048, 132000, 132001, 133010). The first group should stop that lead's step without spending a retry. The second group should stop the whole campaign, because retrying it burns quota to reproduce the same failure. Autocloz maps them into that split so a single bad template does not silently consume an entire enrolment queue, and the refusal reasons surface on the compliance and channel-health views rather than only in a log.

The silent non-delivery that reports itself as success

One failure mode deserves its own section because it produces no error at all, and it is the single most expensive WhatsApp bug a sales team can ship.

Meta's phone-number reference documents that when the recipient value in a send omits the leading + and country code, the Cloud API does not reject it. It prepends the business number's own country code and sends to whatever that produces. Meta's own example: a US recipient typed as (631) 555-1234 on an Indian business number becomes +916315551234.

So the request returns HTTP 200 with a real message id, your CRM records the message as sent, and the message goes to a number in the wrong country or to nobody at all. There is no synchronous error to catch and often no meaningful failure webhook either, because the fabricated number may simply not have a WhatsApp account. Every send from a workspace that imported numbers in national format lands here.

The fix is not clever, it is just mandatory: normalise every recipient to full international form before the request, and refuse the send when you cannot, naming the lead's number as the thing to fix. Autocloz does exactly this — it normalises through libphonenumber, passes through a value that already starts with +, and refuses anything else with a message that explains the silent-misroute behaviour, because refusing costs one lead and sending costs the money plus the belief that it worked.

Autocloz's free plan carries WhatsApp alongside the other four channels on 5 users and 10 mailboxes with a 250-message daily cap on the WhatsApp channel — start free and connect a test number before you register templates you will have to resubmit.

Connecting a number, and what the handshake actually needs

Two friction points account for most failed connections, and neither is obvious from the error you see.

The template body and its variables are two different pieces of information. Meta stores the text and the sample values you declared at submission. It never stores what {{1}} stands for. A system that syncs templates out of WhatsApp Manager therefore imports a body with placeholders and no mapping, and if it falls back to the declared sample it will send Meta's example — "Hi Ada" — to your entire list and report every one as delivered. Autocloz refuses to dispatch a synced template whose placeholders are unmapped, and names how many are unmapped, because a delivered-but-wrong message is worse than a refusal: nobody re-reads a message the dashboard says arrived.

Parameter count is derived from the text, not from your variable list. Meta renumbers gaps at submission, so a body using {{1}} and {{3}} becomes two positions while a naive integration still sends three. That is 132000 for every recipient. Counting placeholders in the body and header separately — they are separate numbering spaces to Meta — is what makes the wire match the approval.

One more that bites on multilingual programmes: the template's language is a property of the template, not a constant. Hardcoding en_US means a Hindi or Spanish template that Meta approved can never be sent, and the failure surfaces as 132001, which reads like an approval problem rather than a locale bug. The wider question of how each channel's ban surface behaves covers how this sits alongside LinkedIn and SMS.

What the API does not give you, and what Autocloz does not do

The API does not give you a way to message someone who has not opted in, and no provider can sell you one. It does not give you read receipts for recipients who disabled them, does not tell you a template was reported rather than merely unread, and does not publish the per-user marketing limit you will eventually hit. It also does not currently deliver marketing-category templates to United States phone numbers at all, which is a planning constraint rather than a configuration one.

On the product side. Autocloz's opt-in enforcement is off by default and enabled per workspace, and even when enabled it gates WhatsApp only — the SMS path checks the do-not-contact list but not the consent ledger. Template approval is entirely Meta's and nothing here accelerates it. The messaging-tier ceiling is applied only where Meta has actually reported a tier the product recognises, and a tier it does not recognise is treated as "not stated" rather than as zero, so your own configured daily limit remains the operative cap in that case.

The 24-hour window is resolved from the conversation record stamped by any inbound message, or from a reply recorded against that handle in the last 24 hours, with handles compared on digits so a differently formatted import still matches. That is deliberately generous, and it can only widen what succeeds rather than narrow it — but it means the window is inferred from your own data rather than queried from Meta, so a message ingested outside the product will not be visible to it.

Self-hosted WhatsApp session transports, where they are used instead of the Cloud API, have no template registry and no 24-hour window, so the approved-template gate does not apply to them at all. That is by design and it is an allow-list rather than a default, but it does mean the behaviour described above is Cloud API behaviour rather than universal. Nothing here is legal advice, and the consent rules that bind you are the recipient's.