The WhatsApp Cloud API is part of the WhatsApp Business Platform and is today’s way to access the WhatsApp Business API. It is the version of the API hosted by Meta itself: the business does not install or maintain the API on its own server; it only integrates its systems over HTTPS and receives events by webhook.
This guide covers how it differs from On-Premises and the app, the access options, the path to production, tokens, webhooks, media, costs, and common mistakes.
Key Takeaways
- Test with the
hello_worldtemplate in the app dashboard before writing any integration code. - In production, use a system user token, register the number with a PIN, and serve the webhook with a valid TLS certificate.
- Download and store inbound media as soon as the event arrives, because the URL expires in minutes.
What Is the WhatsApp Cloud API
Many people search for the term thinking it is an app. The Cloud API has no interface of its own: it is a programming interface that connects a company’s systems to WhatsApp.
Definition and Origin of the Cloud Version
The Cloud API lets a business send messages and make calls on WhatsApp programmatically. Instead of someone typing on a phone, a system sends text, media, and interactive messages based on rules, integrations, or AI agents.
The cloud version opened to all businesses in 2022, according to Meta’s announcement at its Conversations event. The pitch was free hosting on Meta’s own servers and access in minutes, without the infrastructure the previous model required.
People often confuse the API with the WhatsApp Business app, the free app for small businesses. The app is operated by hand on a phone, while the Cloud API is operated by software and scales with teams and automation.
WhatsApp Business Platform Components
The Cloud API handles sending and receiving messages and calls. The Business Management API manages phone numbers, templates, analytics, and costs; webhooks deliver events; and the Marketing Messages API serves campaigns with conversion tracking.
In practice, every project uses at least the Cloud API and webhooks. For the full picture of rules, pricing, and requirements, the WhatsApp Business API guide covers each topic, while this article focuses on technical setup.
HTTPS Calls, Flow, and Statuses
According to Meta’s documentation, every action is an HTTPS request, encrypted with TLS, to a Graph API endpoint. The URL includes the Graph API version (in the /vXX.0/ format) and the ID of the sending phone number.
The current version appears in Meta’s changelog. Pinning the version in code avoids surprises: the integration stays stable until the team tests the new version in staging and migrates, instead of breaking when an old version is no longer accepted.
This model follows the integration pattern used in enterprise AI projects. To send a message, the ERP, CRM, or AI agent makes a POST request with the recipient and the content, without needing someone holding a phone.
Inbound messages and statuses of sent messages, such as delivered and read, come back by webhook. That feedback lets WhatsApp customer service know whether the customer read an update. Outside the 24-hour customer service window, a business can only send approved message templates.
Cloud API vs. On-Premises vs. App, and Access Options
The choice involves two decisions: which model to use and who will run the integration. One of the three models has been retired, the other two serve different needs, and access can be direct or through a provider.
End of On-Premises and the Cloud Standard
Under the sunset schedule Meta published, new features started shipping only in the cloud in January 2024. From July 2024, new phone numbers could only be registered on the Cloud API.
On October 23, 2025, the last On-Premises version expired, and messages from numbers still registered on it stopped being delivered. Since then, the Cloud API has been the only version of the official API in operation.
That is why tutorials that tell you to install your own server are outdated. Customer service automation projects started today are cloud-native, with Meta running the messaging infrastructure.
When the App Is Enough and When to Migrate
The WhatsApp Business app works well for people who serve customers alone or with a small team. When the operation needs several agents, system integration, or automation, the API makes more sense. The table summarizes the differences, based on the official WhatsApp Business comparison.
| Criteria | WhatsApp Business app | WhatsApp Cloud API |
|---|---|---|
| Numbers per account | One number | Multiple numbers and display names |
| Users | Individual use or a small team | Thousands of agents and bots |
| CRM integration | No API integration | Through API and webhooks |
| Automation | Built-in app features | AI agents and integrated flows |
| Cost | Free app | Free hosting; per-message charges (see Meta’s rate card) |
Migrating does not force a business to give up the app. With WhatsApp coexistence, activated through a provider, the same number works in the WhatsApp Business app and the Cloud API at the same time, and messages sent from the app remain free.
Direct Access Through Meta or Through a Provider
The Cloud API is the same on both paths; what changes is who builds, hosts, and maintains the integration. Meta’s get started guide describes direct access: a Meta app with the WhatsApp use case, a WhatsApp Business Account (WABA), and a phone number.
From there, almost everything is code, with a development team and an HTTPS server for webhooks. Anyone who has built chatbots will recognize the work, now combined with managing tokens, webhooks, and Graph API versions.
With a provider, the path is Embedded Signup: the flow opens on the provider’s website, creates the business’s WhatsApp assets, and authorizes the provider’s app to operate the account. Provider types differ in billing and support, so it is worth confirming that the platform uses the official API and how it charges.
Ready-made platforms in the WhatsApp AI tools category follow this model. The platform handles the Meta connection and bundles template campaigns with unsubscribe, re-engagement, CRM and database integrations, and dashboards, while the company’s team works on conversation flows.
How to Get Started with the WhatsApp Cloud API
The path has two phases: seeing the first message arrive on a phone, and then giving the integration permanent credentials and a real number, ready to talk to customers.
Account, Portfolio, and Phone Number Prerequisites
For testing, Meta requires a Facebook account or a Meta managed account, a developer registration, a phone with WhatsApp, and a Meta app with the WhatsApp use case, which holds the dashboard, tokens, and webhook.
For production, a Business Portfolio, formerly Business Manager, is required and holds the WhatsApp Business Accounts. Business verification unlocks more throughput and opens the way to Official Business Account status.
Under Meta’s phone number requirements, the line must belong to the business, include the country and area code, and be able to receive an SMS or a call. Short codes are not accepted.
A number already in use on WhatsApp must be deleted first, except with coexistence. A banned number requires a successful appeal before it can move to the API.
Test Environment and the hello_world Template
Meta creates a test environment in the app dashboard, which lets you send the first message without setting up your own server or webhook. The basic sequence is:
- Create the Meta app and add the WhatsApp use case.
- Click “Generate access token” to create a temporary token.
- Add the phone number that will receive the test.
- Send the
hello_worldtemplate and confirm it arrives on the device.
According to Meta, the temporary token expires quickly and is not suitable for development. To study a complete flow, there is the Jasper’s Market sample app, with the demo code.
With the first message delivered, the next step is deciding what will answer customers. Many teams start with a WhatsApp chatbot for frequently asked questions, while others evaluate AI agents instead of fixed replies only.
From Test to Production
To set up the WhatsApp Cloud API in production, the sequence in Meta’s documentation swaps test credentials for permanent ones and connects a business number:
- Create a system user in the Business Portfolio.
- Generate a permanent token with the
whatsapp_business_messagingpermission. - Add the real number to the WhatsApp Business Account.
- Register the number with
POST /PHONE_NUMBER_ID/registerand a 6-digit PIN.
Number registration has a limit: 10 requests per number every 72 hours, or you get error 133016. The same applies to deregistration, and a deregistered number is unusable until it is registered again.
A payment method and a display name complete the list, and the name must be approved by Meta before customers see it. With everything active, the business can automate customer service on a stable foundation.
Access Tokens, Security, and Data Protection
The token works as the key to the account. If it leaks, anyone can send messages on the company’s behalf, and the damage ranges from brand reputation to the number’s quality rating.
Token Types and When to Use Each
Meta’s access tokens page defines three types. Using the wrong one, such as a user token in production, makes the integration stop sending when the credential expires:
- User token: for testing only; expires within a few hours.
- System user token: long-lived and recommended for direct integrations.
- Business integration token: generated per client and used by providers.
Systems that consume the token, such as support automation tools, should read the credential from a vault or an environment variable. Rotating the token should be a documented procedure, not an emergency.
Protecting Credentials and Customer Data
The token should live only on the server, never in website code, spreadsheets, or team chats. It is also good practice to grant the minimum permission needed and revoke access whenever the company changes vendors.
The WhatsApp Business Messaging Policy requires opt-in, meaning the customer provided the number and gave permission, as well as honoring opt-out. Keep a record of each consent in the contact’s profile.
For businesses serving Brazil, the country’s data protection law (LGPD, in Portuguese) completes the picture; similar rules apply under GDPR in the EU. The company should collect only the data needed for service, define how long it keeps media and conversations downloaded from the API, and give customers a channel to request deletion.
AI agents with access to orders, customer records, or payments require extra care. Rules against prompt hacking stop a malicious message from convincing the agent to reveal data or take unauthorized actions.
WhatsApp Cloud API Webhooks
The webhook is the most technical part of the setup. It is how the business receives messages, statuses, and alerts, so any failure here leaves customer service blind to what is happening.
How to Set Up the Webhook: Verification and Certificate
Meta’s page on how to create a webhook endpoint requires a valid TLS certificate. A self-signed certificate is not accepted, and Meta also supports mTLS for teams that need mutual authentication between servers.
During verification, Meta sends a GET request with the hub.mode=subscribe, hub.challenge, and hub.verify_token parameters. The server checks that the token matches the one configured in the dashboard and responds with 200, returning the challenge.
Once verified, the endpoint forwards events to where they create value. A common destination is a CRM integration that logs each conversation in the customer’s history.
Signature, Retries, and Key Fields
Each POST includes the X-Hub-Signature-256 header. The server should compute the HMAC-SHA256 of the payload with the app secret, compare the values, and discard any request whose signature does not match.
According to the webhooks overview, if the endpoint does not respond with 200, Meta retries the event with decreasing frequency for up to 7 days. That is why deduplicating events is mandatory, using the ID of each message or status.
Each notification can be up to 3 MB, and the server must accept that size. Among the subscription fields, three are central to customer service: messages, with inbound messages and statuses of sent ones; account_alerts, with limit and official account notices; and message_template_quality_update, on template quality.
Delivery and read statuses become management data when they feed customer service metrics, such as response time and the read rate of updates sent by the business.
Messages, Media, and Interactive Features
Beyond text, the Cloud API offers formats that make it easier for customers to reply. They come with file rules that, when ignored, break integrations in production.
Message Types and Flows
Service messages fall into three groups: basic formats, such as text with link previews, image, video, audio, and document; interactive ones, such as reply buttons, lists, location requests, and URL and call buttons; and commerce, with catalog messages and reactions.
Buttons and lists work well for short journeys. A delivery chatbot, for example, can show the menu as a list, confirm the order with buttons, and request the customer’s location to calculate delivery.
For longer journeys, Flows create multi-step forms inside the chat, useful for scheduling, feedback, and lead capture. They can query an endpoint in real time, such as a calendar of open slots.
Media Rules: Sizes and Expiration
Meta’s media rules define uploads through POST /PHONE_NUMBER_ID/media, and uploaded media is stored for 30 days. Size limits by type are:
- Image: up to 5 MB.
- Video and audio: up to 16 MB.
- Document: up to 100 MB.
For inbound media, the download URL expires in 5 minutes. The safe approach is to download the file as soon as the event arrives and store it in your own system, instead of saving only the URL.
This rule is essential for a WhatsApp chatbot that analyzes receipts or product photos. The media ID received by webhook also expires in 7 days, so the file needs to reach the company’s storage in the same flow.
Costs, Limits, and Quality in Practice
Pricing, messaging limits, and the quality rating shape technical planning. Rates and categories are on Meta’s official rate card, cited below.
How Pricing Fits into the Project
Cloud hosting is free. Since July 1, 2025, Meta has charged per delivered message, according to its pricing page. The rate depends on the category (marketing, utility, or authentication) and on the recipient’s country.
Free-form, non-template messages, which can only be sent inside the customer service window, were free through September 30, 2026, as were utility templates sent inside it. From October 1, 2026, Meta charges for both, with 1,000 free service messages delivered per phone number per month; in Brazil, for example, the rate is R$ 0.035 per delivered message. The WhatsApp API pricing guide details the change. Reminders and sales follow-ups sent after the window closes require templates, so it pays to concentrate the conversation while the customer is active.
In Brazil, since March 11, 2026, Meta has charged general-purpose AI providers for non-template messages to +55 numbers. Companies that use AI in their own customer service are not covered by this rule.
Messaging Limits, Throughput, and Quality Rating
Messaging limits rise in tiers of 250, 2,000, 10,000, and 100,000 unique recipients in 24 hours, up to unlimited. Since October 2025, according to the messaging limits change notice, the limit applies per portfolio, and a quality drop no longer downgrades the tier.
Quality matters in another way: under the template pausing rules, templates with negative signals are paused for 3 hours, then for 6 hours, and disabled if the problem persists. The platform overview sets default throughput at 80 messages per second per number.
There is also a pair rate limit of one message every 6 seconds to the same user. High quality comes from relevant messages, and well-segmented customer retention strategies help maintain it.
Use Cases and Common Implementation Mistakes
With the API configured, value shows up in the use cases. The road there can hit predictable errors, almost all related to tokens, webhooks, and number registration.
Use Cases with AI Agents and Integrations
The most complete use is AI agents that serve customers around the clock and take actions in other systems, such as checking an order, issuing a duplicate invoice, or booking an appointment.
Other common uses are transactional notifications and reminders, contact re-engagement, bulk messaging with templates and an unsubscribe button, and sales funnel stages that depend on a fast response.
Pre-Production Error Checklist
The points from the previous sections become a quick check before going live. Each item below blocks activation or breaks delivery when it goes unnoticed:
- Temporary token in production: replace it with the system user’s permanent token.
- Webhook not returning 200: respond quickly and deduplicate retries.
- Self-signed certificate: use a valid TLS certificate on the endpoint.
- Repeated number registration: plan activation to avoid error 133016.
- Stored media URL: save the file, not the link that expires in minutes.
- Sending without opt-in: reports lower quality and increase the risk of a block.
WhatsApp Cloud API FAQ
In practice, they are the same official API. The term Cloud refers to the version hosted by Meta, the only one in operation since On-Premises ended in October 2025. Anyone connecting a number to the official API today uses the Cloud API.
Any language that can make HTTPS requests and receive webhooks, because the API is based on HTTP and the Graph API. The choice depends on the team and the server hosting the endpoint, which needs a valid TLS certificate.
Yes, in coexistence mode. The WhatsApp Business app stays on the phone and supports up to four linked devices, such as WhatsApp Web; the exceptions are the Windows and WearOS versions. During activation, devices are unlinked and must be connected again.
The test environment is ready quickly in the app dashboard. Production depends on steps such as portfolio verification, display name approval, and number registration, and the timeline varies case by case.
Yes. Meta’s documentation lists calls and groups among Cloud API features, alongside text, media, and interactive messages. Both are triggered through the same HTTPS integration used for messages.
An Official Business Account requires a verified portfolio, active two-step verification, an approved display name, at least 30 days on the platform, and policy compliance. The request is made in WhatsApp Manager or through the API.
The cloud is now the standard for the official API, and a project comes down to three fronts: validate the idea in the test environment, swap temporary credentials for a system user with a registered number, and prepare the webhook and media handling for retries and short deadlines. With that foundation, automation grows without rework.
To put AI agents to work on the official API with coexistence, talk to the ConverZap team.
