Developer guide · 2026

WhatsApp Cloud API – Complete Guide

Meta gives you the messaging API—not a team inbox, chatbot builder or operations dashboard. This guide covers the supported Cloud API, what you need to build yourself, and when a platform like WhatsEase is the better fit.

Meta-hosted Cloud APIGraph API v27.0Code examples included
Message flow

Your app talks to Meta’s API

Meta hosts the messaging infrastructure. You handle the product layer.

Your appAPI requests
Cloud APIMeta-hosted
CustomerWhatsApp
Delivery updates and inbound messages arrive by webhook
API version shown in examples: v27.0
01Start with the basics

What is the WhatsApp Cloud API?

The WhatsApp Cloud API is Meta’s hosted version of the WhatsApp Business Platform. Your server calls Graph API endpoints to send messages; Meta handles the underlying WhatsApp messaging infrastructure and sends inbound messages and delivery updates to your webhook.

The Cloud API is the supported path for new builds. Meta’s On-Premises API is no longer supported, so new integrations should not follow old self-hosted setup instructions. The API itself is a set of endpoints and webhooks—there is no built-in shared inbox, agent UI or visual chatbot builder.

Use the current Graph API version. The examples below use v27.0 and placeholders for IDs and secrets. Check Meta’s current release notes before production and keep access tokens on your server.

Reference: Meta’s official WhatsApp Cloud API documentation.

02Pick your integration path

Direct Meta integration vs using a platform

Direct integration gives your engineering team control. A platform adds the operational interface that the raw API leaves to you.

Comparison of integrating directly with Meta's Cloud API and using WhatsEase.
What you needDirect with MetaBuild on Cloud APIWhatsEase platformAPI + operating layer
Setup timeEngineering team wires app, number, tokens, webhook, retries and storage. Scope depends on your product.Guided onboarding with core conversation tools ready to configure.
Inbox UINone included. Build agent assignment, conversation history and permissions yourself.Shared team inbox for agents to manage customer chats.
Chatbot builderImplement flows, routing, state and handoff in your own application.Build and manage customer workflows with platform tools.
TemplatesSubmit through Meta and build your own tools for template management and delivery status.Manage templates and campaign workflows alongside conversations.
IntegrationsDevelop and maintain each CRM, commerce and internal-system connector.Use REST API, webhooks and available integrations to connect your stack.
MaintenanceOwn token security, webhook verification, retries, monitoring, opt-in records and UI.WhatsEase provides the operating layer; your team still follows Meta policies and maintains its own application integrations.

Meta message charges can apply with either route. A platform may also have separate subscription or usage fees.

Choose direct if…

You have engineering capacity, need full control and are ready to build the inbox and operations layer yourself.

Choose a platform if…

Your team needs a shared inbox, automation and integrations without building every operational tool from scratch.

03Setup walkthrough

Connect a number and configure the API

The exact labels in Meta’s developer dashboard can change. These illustrative screen previews show the decisions you’ll make—not screenshots of Meta’s live product.

1

Create a Meta app

Use a business app, add the WhatsApp product and connect the right business portfolio.

App dashboardBusiness
App nameCustomer messaging
App modeDevelopment ✓
2

Add WhatsApp

Open the WhatsApp API setup and select or create the WhatsApp Business Account (WABA).

App productsConnected
WhatsAppAdded ✓
Business accountWABA selected
3

Register a phone number

Use a test number to start. Note the Phone Number ID and create a production token with only the required permissions.

API setupTest number
Phone Number ID••••••••••••
Access tokenServer-side only
4

Configure a webhook

Set an HTTPS callback URL, complete the challenge handshake, then subscribe the app to the messages field.

WebhooksSubscribed
Callback URL/webhooks/whatsapp
messagesSubscribed ✓

Illustrative dashboard previews · Meta may update product labels and setup requirements.

Temporary access tokens are for development. Store production tokens and the Meta app secret in a server-side secret manager or environment configuration—never in browser code or a public repository.
04Make your first request

Send a template message and verify webhooks

These server-side examples (cURL, Python and Node.js) use Graph API v27.0. Replace the sample recipient and template with a number that has opted in and a template approved for your WhatsApp Business Account.

Send a template cURL
POST /messages
curl --request POST \
  "https://graph.facebook.com/v27.0/${PHONE_NUMBER_ID}/messages" \
  --header "Authorization: Bearer ${WHATSAPP_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "messaging_product": "whatsapp",
    "to": "RECIPIENT_PHONE_E164",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en_US" }
    }
  }'
Send a template Python
requests
import os
import requests

url = f"https://graph.facebook.com/v27.0/{os.environ['PHONE_NUMBER_ID']}/messages"
headers = {
    "Authorization": f"Bearer {os.environ['WHATSAPP_ACCESS_TOKEN']}",
    "Content-Type": "application/json",
}
payload = {
    "messaging_product": "whatsapp",
    "to": os.environ["TEST_RECIPIENT"],
    "type": "template",
    "template": {
        "name": "hello_world",
        "language": {"code": "en_US"},
    },
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
result = response.json()
print(result.get("messages", [{}])[0].get("id"))
Send a template Node.js
Node 18+ fetch
const response = await fetch(
  `https://graph.facebook.com/v27.0/${process.env.PHONE_NUMBER_ID}/messages`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHATSAPP_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      to: process.env.TEST_RECIPIENT,
      type: "template",
      template: {
        name: "hello_world",
        language: { code: "en_US" },
      },
    }),
  },
);

if (!response.ok) {
  throw new Error(`Meta API error: ${response.status}`);
}
const result = await response.json();
console.log(result.messages?.[0]?.id);

Keep the token on your server. hello_world is a sample template; use an approved template name and language for your account. In Python, install requests via pip install requests.

Verify the challenge and request signature Express
GET + POST /webhooks/whatsapp
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();

app.get("/webhooks/whatsapp", (req, res) => {
  const mode = req.query["hub.mode"];
  const token = req.query["hub.verify_token"];
  const challenge = req.query["hub.challenge"];

  if (mode === "subscribe" &&
      token === process.env.WEBHOOK_VERIFY_TOKEN &&
      typeof challenge === "string") {
    return res.status(200).type("text/plain").send(challenge);
  }
  return res.sendStatus(403);
});

function isValidSignature(rawBody, signature) {
  if (!signature?.startsWith("sha256=")) return false;
  const expected = Buffer.from(
    `sha256=${createHmac("sha256", process.env.META_APP_SECRET)
      .update(rawBody).digest("hex")}`,
  );
  const received = Buffer.from(signature);
  return received.length === expected.length &&
    timingSafeEqual(received, expected);
}

// Register this before any JSON body parser so the raw bytes are preserved.
app.post("/webhooks/whatsapp",
  express.raw({ type: "application/json" }), (req, res) => {
    if (!isValidSignature(
      req.body,
      req.get("x-hub-signature-256"),
    )) return res.sendStatus(401);

    // Enqueue the verified event; acknowledge quickly.
    return res.sendStatus(200);
  },
);
Handshake token ≠ app secretThe verify token is a secret you choose for the GET challenge. The POST signature uses your Meta app secret.
Verify before processingValidate X-Hub-Signature-256 against the exact raw body, then queue work and respond quickly.
05Events and approved content

Webhooks and message templates

A Cloud API integration is a two-way system: send requests to Graph API, then use webhooks to learn what customers send and what happens to your outbound messages.

Subscribe to the events you need

Configure an HTTPS callback, complete Meta’s GET verification challenge and subscribe your app to the messages webhook field. The field can carry inbound messages and message-status updates. Verify each POST signature using the raw request body, acknowledge valid events quickly, and process retries or longer work through a queue.

Use templates for business-initiated messages

When your business starts a conversation, use an approved template and respect customer opt-in. Meta reviews template content and assigns a category. Keep a clear separation between operational updates, promotions and one-time verification codes.

Utility

Order and account updates

Transactional notifications tied to a user action or service request.

Marketing

Offers and announcements

Promotions, product discovery and re-engagement messages.

Authentication

One-time passcodes

Verification codes and account authentication journeys.

During the customer service window, your app can reply with free-form messages. Outside that window, use an approved template to initiate or resume a conversation. Category rules, templates, limits and charges can change—check the current account settings and rate card.
06Budget for both layers

WhatsApp Cloud API pricing

Using Meta’s Cloud API directly does not mean every part of your messaging stack is free. Meta message charges and your own infrastructure costs sit alongside any platform fee.

Meta pricing depends on the current market rate, message category and applicable conversation rules. A platform may add a subscription or usage fee for inbox, automation, support and integrations. Because Meta can update rates and categories, use a current breakdown rather than relying on old per-conversation estimates.

See the current WhatsApp API pricing breakdown

Compare Meta message charges with WhatsEase plans and understand which tools are included.

View pricing
07Use the API through WhatsEase

Keep the API. Add the operating layer.

WhatsEase is for teams that want the Cloud API’s reach without building every agent-facing tool themselves. Use the shared inbox and workflow layer, then connect your own software through the REST API and webhooks.

Need to connect your existing stack? Browse all docs and integrations.Developer docs · Integrations
08Common questions

WhatsApp Cloud API FAQs

What is the WhatsApp Cloud API?

The WhatsApp Cloud API is Meta’s hosted API for the WhatsApp Business Platform. Developers use Graph API endpoints to send messages and receive webhook events without operating the messaging infrastructure themselves.

Is the WhatsApp On-Premises API still supported?

No. Meta’s On-Premises API is no longer supported. New integrations should use the Cloud API or a platform built on the supported Cloud API.

Do I need a platform to use the WhatsApp Cloud API?

No. Developers can integrate directly with Meta’s Cloud API. A platform is useful when you also need a shared team inbox, workflow builder, integrations and ongoing operational tooling.

Can I use Python with the WhatsApp Cloud API?

Yes. Meta’s WhatsApp Cloud API uses standard HTTPS REST endpoints, so you can send messages and manage templates in Python using HTTP libraries like requests or urllib.

How do I verify a WhatsApp webhook?

For webhook setup, handle Meta’s GET challenge using your verify token. For each POST notification, verify the X-Hub-Signature-256 HMAC against the exact raw request body using your Meta app secret before processing it.

Do WhatsApp message templates need approval?

Business-initiated templates must follow Meta’s content and opt-in policies and are reviewed by Meta. Template categories include marketing, utility and authentication; availability and review outcomes can change.

How much does the WhatsApp Cloud API cost?

Meta message charges depend on the current rate card, market, message category and applicable conversation rules. A third-party platform may also charge a separate subscription or usage fee.

Build less infrastructure

Get Cloud API capability with a team-ready workspace.

See how WhatsEase connects WhatsApp messaging to your team inbox, workflows and integrations.