# WhatsApp Business Platform: Cloud API and templates

> The WhatsApp Business Platform sends messages through the Cloud API (hosted by Meta) or the legacy On-Premises API. Business-initiated messages must use pre-approved templates in a category (marketing, utility, authentication); free-form session messages are allowed only inside a 24-hour customer-service window opened by the user's last message. Opt-in is mandatory.

- Canonical URL: https://www.broadnet.me/reference/whatsapp-business-cloud-api
- Language: en
- Last updated: 2026-07-18
- Publisher: BroadNet (https://www.broadnet.me)

How the WhatsApp Business Platform works: Cloud API vs On-Premises API, template (HSM) messages vs session messages, the 24-hour customer service window, the marketing/utility/authentication categories, webhooks, phone-number quality tiers and opt-in.

## Cloud API vs On-Premises API

The WhatsApp Business Platform exposes two APIs with the same messaging model but different hosting. The Cloud API is hosted by Meta: a business (or its solution provider) calls a Graph-style REST endpoint keyed on a phone-number ID, with no local client to run. The On-Premises API is a containerised client the business hosts itself, historically used for data-residency or latency reasons; Meta has designated it for sunset in favour of the Cloud API. Both are governed by the same rules — templates, the 24-hour window, categories, quality and opt-in — so the choice is operational (who hosts) rather than functional.

*Cloud API vs On-Premises API*

| Property | Cloud API | On-Premises API |
|---|---|---|
| Hosting | Meta-hosted, no client to run | Business-hosted containerised client |
| Endpoint | Graph REST on a phone-number ID | Local client REST endpoint |
| Upgrades | Managed by Meta | Business maintains client versions |
| Status | Recommended, actively developed | Designated for sunset |
| Rules (templates/window/quality) | Identical | Identical |

## Template (HSM) messages vs session messages

WhatsApp separates the two directions of business messaging. A business cannot cold-message a user with free-form content: any business-initiated message must be a message template — historically called a Highly Structured Message (HSM) — that has been submitted to and approved by WhatsApp in advance, with named variable placeholders and a declared category. Once the user replies, a 24-hour customer-service window opens in which the business may send free-form session messages (text, media, interactive) without a template. Outside that window, the business must again start with an approved template. This template-first rule is the core constraint of the platform.

*Cloud API: send an approved utility template*

```json
POST https://graph.facebook.com/v20.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_shipped",
    "language": { "code": "en_US" },
    "components": [
      { "type": "body",
        "parameters": [ { "type": "text", "text": "4021" } ] }
    ]
  }
}
```

## The 24-hour customer-service window

The 24-hour window is the mechanism that gates free-form messaging. It opens (or re-opens) each time the user sends a message to the business, and it lasts 24 hours from that last user message. Inside the window the business may reply with any allowed message type — plain text, media, interactive buttons or lists — without using a template. When the window closes, free-form sends are rejected and the business must re-engage with an approved template (subject to category and, for marketing, per-user limits). Session pricing and the newer per-message pricing both hinge on whether a send falls inside or outside this window.

## Message categories: marketing, utility, authentication

Every template is assigned a category that governs how it may be used and how it is priced. Utility templates relate to a specific, agreed transaction or account event (order updates, appointment reminders, statements). Authentication templates deliver one-time passcodes and verification, with a constrained format. Marketing templates carry promotions, offers and re-engagement and are the most tightly governed — subject to user opt-in, quality signals and frequency limits. WhatsApp reviews the template content against the declared category on approval and may re-categorise it; sending marketing content under a utility label is a common cause of rejection or quality damage.

*WhatsApp template categories*

| Category | Purpose | Notes |
|---|---|---|
| Utility | Transaction / account updates the user expects | Tied to a specific action or agreement |
| Authentication | One-time passcodes, verification | Constrained format; OTP-focused |
| Marketing | Promotions, offers, re-engagement | Strict opt-in, quality and frequency governance |
| Service (session) | Free-form replies in the 24h window | No template required; not business-initiated |

## Webhooks: inbound messages and delivery status

The platform is asynchronous and callback-driven. A business configures a webhook URL to which WhatsApp posts two kinds of events: inbound messages (the user's replies, media, button taps, location) and status notifications for outbound messages, which progress through sent, delivered, read and — on failure — failed with an error code. Read receipts and the message lifecycle are surfaced here, and the arrival of an inbound message event is exactly what opens or refreshes the 24-hour window. A robust integration acknowledges webhooks quickly and reconciles delivery status against its own message store, much as an SMS platform reconciles DLRs.

*Inbound webhook: user message opens the 24-hour window*

```json
{
  "entry": [{ "changes": [{ "value": {
    "messaging_product": "whatsapp",
    "messages": [{
      "from": "15551234567", "id": "wamid.HBg...",
      "timestamp": "1752796800",
      "type": "text", "text": { "body": "Where is my order?" }
    }]
  } }] }]
}
```

## Phone-number quality, tiers and opt-in

Each business phone number carries a quality rating (shown as high/medium/low, often coloured green/yellow/red) derived from how users react to its messages — blocks and reports pull it down. Quality gates the messaging limit tier, which caps how many unique users a number may start conversations with in a rolling 24 hours; tiers step up (for example 250, 1K, 10K, 100K, then unlimited) as quality and volume are sustained, and drop if quality falls. Underlying everything is opt-in: WhatsApp requires businesses to obtain and record explicit user consent, collected on any channel, before sending. Poor opt-in practice shows up quickly as blocks, degraded quality and a throttled tier.

*Quality rating and messaging tiers*

| Signal | Meaning | Effect |
|---|---|---|
| Quality: high (green) | Few blocks/reports | Eligible to scale up tiers |
| Quality: medium (yellow) | Some negative feedback | Under observation; scaling paused |
| Quality: low (red) | Many blocks/reports | Risk of tier downgrade or flagging |
| Tier (250 / 1K / 10K / 100K / ∞) | Unique users started per 24h | Raised on sustained quality + volume |
| Opt-in | Recorded user consent | Required before any business-initiated send |

## Frequently asked questions

### What is the difference between the Cloud API and the On-Premises API?

Both use the same WhatsApp messaging model, but the Cloud API is hosted by Meta (you call a REST endpoint, nothing to run), while the On-Premises API is a containerised client you host yourself. Meta has designated the On-Premises API for sunset in favour of the Cloud API. Templates, the 24-hour window, categories and quality rules apply identically to both.

### What is a WhatsApp message template (HSM)?

A template — historically a Highly Structured Message — is pre-approved content with named variable placeholders and a declared category. Any business-initiated WhatsApp message must be a template; free-form content is only allowed inside the 24-hour customer-service window opened by a user's reply.

### What is the 24-hour customer-service window?

It is the period, lasting 24 hours from the user's last message to the business, during which the business may send free-form session messages without a template. When it closes, free-form sends are rejected and the business must re-engage using an approved template. Inbound webhook events open or refresh the window.

### What are the WhatsApp message categories?

Templates are categorised as utility (transaction/account updates the user expects), authentication (one-time passcodes and verification), or marketing (promotions and re-engagement, the most strictly governed). Free-form replies inside the window are service messages. The category governs allowed use and pricing, and WhatsApp reviews content against the declared category.

### What determines a WhatsApp number's messaging limit?

The messaging tier caps how many unique users a number can start conversations with per rolling 24 hours (for example 250, 1K, 10K, 100K, then unlimited). Tiers rise on sustained quality and volume and fall if quality drops. Quality is a high/medium/low rating driven by user blocks and reports.

### Do I need opt-in to message users on WhatsApp?

Yes. WhatsApp requires explicit, recorded user consent — which may be collected on any channel — before a business sends messages. Weak opt-in shows up fast as blocks and reports, which lower the number's quality rating and can throttle or downgrade its messaging tier.

## Sources

- [WhatsApp Business Platform — Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api)
- [WhatsApp — Message templates and categories](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)
- [WhatsApp — Per-message pricing and the 24-hour window](https://developers.facebook.com/docs/whatsapp/pricing)

## Related

- [WhatsApp Business API](https://www.broadnet.me/products/whatsapp-business-api)
- [RCS vs SMS vs WhatsApp](https://www.broadnet.me/reference/rcs-vs-sms-vs-whatsapp-channels)
- [Rich cards and interactive messaging](https://www.broadnet.me/reference/rich-cards-and-interactive-messaging)
- [Channel fallback and orchestration](https://www.broadnet.me/reference/channel-fallback-and-orchestration)
- [Omnichannel](https://www.broadnet.me/products/omnichannel)
- [Developers](https://www.broadnet.me/developers)