WhatsApp Cloud API: a developer guide

The WhatsApp Cloud API is Meta's hosted API for the WhatsApp Business Platform. You send messages with HTTP requests and receive replies through webhooks. This guide covers setup, code, webhooks, templates, and pricing.

Start building for free Jump to the code

3B+

WhatsApp users you can reach

2 min

to your first message with Kapso

Free

to start, with a sandbox number

Official Meta Business Partner

What is the WhatsApp Cloud API?

It is the API for WhatsApp Business, hosted by Meta. Your app sends messages with HTTP requests, and Meta sends replies and delivery updates back to your webhook.

Phone number ID
The business number you send from. Every request targets it by ID.
Access token
A system user token from Meta, or a provider API key, authorizes each request.
Webhook
Your HTTPS endpoint. Incoming messages and delivery statuses arrive here.
Template
A message format that Meta approves. You need one to start a conversation.
24-hour window
After a customer messages you, you can reply with any message type for 24 hours.
Pricing
Meta charges for each delivered template, by category and recipient country.

Set up the Cloud API

Connect directly to Meta or through a provider. Both paths use the same API and the same message format.

About an hour

Direct with Meta

  1. Create a Meta app

    In Meta for Developers, create an app of type Business and add the WhatsApp product.

  2. Use the test number

    Meta gives you a test number and a temporary token. You can message up to five verified recipients.

  3. Create a permanent token

    The temporary token expires after 24 hours. Generate a system user token with the WhatsApp messaging and management permissions.

  4. Add your phone number

    Verify and register a real number, and set a display name that Meta approves.

  5. Configure webhooks

    Set a callback URL and verify token, and subscribe to the messages field.

  6. Verify your business

    Complete business verification and add a payment method to message more customers.

About two minutes

With Kapso

  1. Sign up for free

    Create a Kapso project. You do not need a credit card.

  2. Get a number

    Use the free sandbox number, or connect your own number with Meta Embedded Signup.

  3. Create an API key

    Create a project API key under Integrations → API keys.

  4. Send a message

    Use the same Cloud API payloads with the Kapso base URL, or the SDK, CLI, or MCP server.

Send your first message

POST to the messages endpoint of your phone number. The payload is the same with Meta or Kapso. Only the base URL and the auth header change.

curl · direct to Meta
curl -X POST "https://graph.facebook.com/v24.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $WHATSAPP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "15551234567",
    "type": "template",
    "template": { "name": "hello_world", "language": { "code": "en_US" } }
  }'
send.ts · npm install @kapso/whatsapp-cloud-api
import { WhatsAppClient } from "@kapso/whatsapp-cloud-api";

const client = new WhatsAppClient({
  // Direct to Meta: accessToken: process.env.WHATSAPP_TOKEN
  baseUrl: "https://api.kapso.ai/meta/whatsapp",
  kapsoApiKey: process.env.KAPSO_API_KEY!,
});

await client.messages.sendText({
  phoneNumberId: process.env.PHONE_NUMBER_ID!,
  to: "+15551234567",
  body: "Hello from the Cloud API",
});

Templates and the 24-hour window

After a customer messages you, you can reply freely for 24 hours. Outside that window, you can only send a template that Meta has approved.

POST /{phone-number-id}/messages · template
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "order_update",
    "language": { "code": "en_US" },
    "components": [{
      "type": "body",
      "parameters": [{ "type": "text", "text": "#1042" }]
    }]
  }
}

Receive messages with webhooks

Meta sends incoming messages and delivery statuses to your endpoint. Verify the URL once, then check the signature on every request.

With Kapso, you get one signed event per message, with automatic retries.

Explore Kapso webhooks
server.ts · Meta webhook
// Meta verifies your URL once with a GET request
app.get("/webhook", (req, res) => {
  if (req.query["hub.verify_token"] !== process.env.VERIFY_TOKEN) return res.sendStatus(403);
  res.send(req.query["hub.challenge"]);
});

// Messages and statuses arrive as signed POST requests
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const valid = verifySignature({
    appSecret: process.env.META_APP_SECRET!,
    rawBody: req.body,
    signatureHeader: req.get("x-hub-signature-256"),
  });
  if (!valid) return res.sendStatus(401);

  const { messages, statuses } = JSON.parse(req.body).entry[0].changes[0].value;
  res.sendStatus(200);
});

Everything around the Cloud API

The Cloud API sends and receives messages. Kapso adds the pieces you would otherwise build yourself.

WhatsApp API sandbox

Send and receive real WhatsApp messages from your own phone before business verification. Included in every plan.

Explore the sandbox

Embedded inbox

Add a ready-made WhatsApp inbox to your app, so your team can read conversations and take over from automation.

Inbox docs

Customer connection links

Let each of your customers connect their own WhatsApp Business number to your product in a few clicks.

Connect customer numbers

AI agents and workflows

Reply with AI agents, run workflows on incoming messages, and hand off to a human when needed.

Explore AI agents

WhatsApp Flows

Build forms, bookings, and sign-ups that open inside the chat, with data endpoints you control.

Explore WhatsApp Flows

WhatsApp Cloud API pricing

There are two costs: Meta's fee for each message, and your provider's platform fee.

Templates

Charged per delivery, by category and country.

Service replies

Free until October 1, 2026. Then 1,000 free per month.

Incoming messages

Always free.

Estimate your Meta fees Read the pricing guide

Kapso plans

Start free. Kapso passes Meta's fees through at cost, without a markup.

Free

$0/month

2,000 messages, one connected phone number plus the Kapso sandbox, unlimited API calls, AI agents, and workflows.

Pro

$25/month

100,000 messages, 3 connected phone numbers, 100 GB media storage, integrations, and 1,000,000 function calls.

Platform

$299/month

1,000,000 messages, 50 connected phone numbers, customer onboarding, platform APIs, and webhooks.

Enterprise

Custom

Custom pricing, custom limits, custom SLAs, dedicated support, and priority feature requests.

See Kapso pricing, or compare Kapso with Twilio.

Common Cloud API errors

A send request can succeed and the message can still fail later. These are the errors developers see most often.

Error 131047

You sent a free-form message outside the 24-hour window. Send a template instead.

Error 131049

Meta limited marketing messages to this user to protect engagement.

Error 131042

The WhatsApp Business Account has a billing or payment method problem.

Frequently asked questions

What is the WhatsApp Cloud API?

The WhatsApp Cloud API is the HTTP API for the WhatsApp Business Platform, hosted by Meta. You send messages with POST requests to the Graph API and receive incoming messages and delivery statuses through webhooks. Meta runs the servers, so you do not host any WhatsApp software yourself.

Is the WhatsApp Cloud API free?

Access to the API is free, but Meta charges for each delivered template message. The price depends on the message category (marketing, utility, or authentication) and the recipient's country. Incoming messages are free. Service messages, your replies inside the 24-hour customer service window, are free until October 1, 2026. From that date, each phone number gets 1,000 free service messages per month, and Meta charges for each delivered service message after that, except in the free 72-hour window that opens when a chat starts from a click-to-WhatsApp ad.

What is the difference between the Cloud API and the WhatsApp Business API?

The WhatsApp Business API is the general name for programmatic access to the WhatsApp Business Platform. The Cloud API is the version that Meta hosts. Meta has retired the self-hosted On-Premises API, so new integrations use the Cloud API, either directly or through a provider such as Kapso.

Do I need business verification to use the Cloud API?

Not to start. Meta gives you a test number that can send messages to a small list of verified recipients. To message customers at scale, you need a business portfolio, a phone number that is registered to WhatsApp, and, for higher messaging limits, business verification.

Can I send any message to any user?

No. You can send free-form messages only within 24 hours of the last message from that person. Outside that window, you must send a template that Meta has approved. If you do not, the message fails with error 131047.

How does Kapso relate to the Cloud API?

Kapso is an official Meta Business Partner built on the Cloud API. Kapso keeps the same request and response format as Meta, adds a free sandbox number, structured webhooks with retries, message history, an inbox, and workflows, and does not add a markup to Meta fees.

Send your first Cloud API message today

Start with the free sandbox number, use the same Cloud API payloads, and connect your own number when you are ready.

Start free Read docs