The WhatsApp Business Platform is one of the most requested messaging channels in customer-facing products, and since Meta introduced the Cloud API, getting started no longer requires hosting a containerised on-premises client. But the platform has its own vocabulary, approval flows and rules that surprise teams coming from plain SMS or email. This guide walks through the architecture and the concepts that matter most when you start writing code.
How the account hierarchy is structured
Before a single API call works, several objects have to exist and be linked correctly:
- Meta Business Manager (Business Portfolio) — the top-level entity that owns your assets. Business verification (legal documents, address, domain) is normally required before you can lift the initial messaging restrictions.
- WhatsApp Business Account (WABA) — a container for phone numbers, message templates and analytics. One business can hold multiple WABAs.
- Phone number — each number gets a
phone_number_id, which is what you actually address in API calls. A number cannot be simultaneously registered in the consumer WhatsApp app and the Business Platform. - Display name — the name shown to recipients. It goes through a review and must reflect the real business.
- App and access token — a Meta app with the WhatsApp product added. For production, generate a long-lived token via a system user rather than relying on temporary user tokens.
You can integrate directly with Meta or go through a Business Solution Provider (BSP). Direct integration gives you full control; a BSP typically handles onboarding, billing consolidation and support. Both use the same Graph API surface.
The Cloud API in practice
Cloud API is hosted by Meta, so you send HTTPS requests to the Graph API instead of running your own client. The core endpoint is a POST to /{phone_number_id}/messages with a JSON body describing the recipient and the message object. Message types include text, image, document, audio, video, sticker, location, contacts, interactive (buttons, lists, call-to-action URLs) and template.
Media can be sent either by passing a public URL or by uploading first to /media and referencing the returned media ID. Inbound media arrives as an ID that you must download with a separate authenticated request — the URL you receive is short-lived.
Everything asynchronous comes back through webhooks: inbound messages, delivery statuses (sent, delivered, read, failed), template status changes and quality updates. Two implementation details trip people up regularly:
- Webhook verification uses a GET request with
hub.mode,hub.verify_tokenandhub.challenge; you must echo the challenge back as plain text. - Payloads are signed with
X-Hub-Signature-256. Validate that HMAC against your app secret before trusting anything, and respond with 200 quickly — process the work in a queue, not inline.
Webhooks can be redelivered, so treat inbound events as at-least-once and deduplicate on the message ID.
Session windows: the rule that shapes everything
WhatsApp is not a broadcast channel. When a user messages your business, a customer service window of 24 hours opens, during which you can reply with free-form messages of any supported type. The window resets each time the user sends a new message.
Outside that window — or when you initiate contact — you may only send a pre-approved template message. There is no way around this, and it is the single biggest architectural difference from SMS. Your application should therefore always know whether an open session exists for a given contact, and fall back to a template (or another channel) when it does not.
Message templates and categories
Templates are created in the Business Manager UI or via the API, and each is submitted for review. They are classified into categories — broadly utility (transaction-related notifications), authentication (one-time passcodes) and marketing (promotions, re-engagement). Category matters because it drives both policy review and pricing.
Practical points for developers:
- Templates support variable placeholders, header media, quick-reply buttons and URL buttons with a dynamic suffix.
- Meta may re-categorise a template if the content does not match the declared category. Keep utility templates strictly transactional.
- Rejections are common for vague variables, missing sample values or promotional language in a utility template. Provide realistic examples on submission.
- Authentication templates follow a stricter, more rigid format designed for one-time codes, including copy-code buttons.
- Editing an approved template resubmits it for review, so version templates in your codebase rather than mutating them freely.
Opt-in, quality rating and limits
WhatsApp policy requires explicit opt-in collected through any channel, with a clear statement that the user will receive messages from your business on WhatsApp. Store the timestamp, source and wording of that consent.
Each number carries a quality rating derived largely from user blocks and "report" actions. Poor quality can push a number into a restricted state and lower its messaging limit; consistent good behaviour raises the tier over time. Sending high volumes of unwanted marketing templates is the fastest way to damage a number that took weeks to warm up.
Pricing has evolved several times, moving from conversation-based to per-message billing for templates, with rates that differ by category and destination country. Never hard-code assumptions — read Meta's current rate card for the markets you serve.
Where SMS still fits
WhatsApp works only if the recipient has the app, has opted in, and your template is approved. For time-critical one-time passcodes and transactional alerts, many teams keep SMS as the primary or fallback path because delivery does not depend on app installation or session state. Designing a channel abstraction early — with per-message routing rules and a shared delivery-report model — saves a rewrite later.
UIPAPP operates in that SMS and OTP layer, with a REST API, webhooks and delivery reports that can sit alongside a WhatsApp integration as a fallback route. WhatsApp and Telegram are our support channels, not products we resell.