> Note (November 2026): This article uses Zavu SDK packages for Python, Ruby, Go or PHP that are no longer maintained, so some examples may not work as shown. The maintained SDK is TypeScript (@zavudev/sdk). From any other language, call the REST API directly or generate a client from the OpenAPI spec. See SDKs and alternatives.
The WhatsApp Cloud API is Meta's official API to send and receive WhatsApp Business messages, hosted by Meta itself (no need to self-host). This tutorial walks you from zero to first message sent, with real code in Python and Node.js.
What the WhatsApp Cloud API is
Cloud API replaced the older "On-Premises API" in 2022. Differences:
| Cloud API (current) | On-Premises (legacy) |
|---|---|
| Hosted by Meta | You host it |
| Setup in hours | Setup in weeks |
| No servers to maintain | VPS + Docker + maintenance |
| Same performance | More complex |
| Recommended for 99% of cases | Only specific enterprise cases |
You don't have to deal with the Cloud API directly. Official providers (BSPs) like Zavu abstract the complexity. But understanding what's underneath is useful.
Prerequisites
Before you start:
Path 1: Direct via Meta (complex)
If you want to go direct via Meta without a BSP:
terminalcurl -X POST \ "https://graph.facebook.com/v18.0/<PHONE_NUMBER_ID>/messages" \ -H "Authorization: Bearer <ACCESS_TOKEN>" \ -H "Content-Type: application/json" \ -d '{ "messaging_product": "whatsapp", "to": "14155551234", "type": "template", "template": { "name": "hello_world", "language": { "code": "en_US" } } }'
That path works, but you still need to:
- Approve templates manually in Meta Business Suite
- Handle token renewal
- Implement signed webhooks
- Manage errors and retries
- Migrate numbers if Meta limits you
Path 2: Via official BSP (recommended)
Official BSPs solve 90% of the complexity. Here's how with Zavu:
1. Create free account
zavu.dev/en — no credit card.
2. Connect Meta Business
In the dashboard, click Add WhatsApp Sender and follow the OAuth flow. You're redirected to Meta, authorize Zavu as BSP, return. Takes 5 minutes.
3. Install the SDK or an HTTP client
Zavu's official SDK is TypeScript. From Python, or any other language, call the REST API directly: https://api.zavu.dev, an Authorization: Bearer header and a JSON body.
terminal# Node.js npm install @zavudev/sdk
terminal# Python (plain HTTP, no Zavu package needed) pip install requests
4. Send first message
Node.js / TypeScript:
TypeScriptimport Zavu from "@zavudev/sdk" const zavu = new Zavu({ apiKey: process.env.ZAVUDEV_API_KEY }) const result = await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", text: "Hi! First message via Zavu." }) console.log(result.message.id, result.message.status)
Python (REST API):
Pythonimport os import requests response = requests.post( "https://api.zavu.dev/v1/messages", headers={ "Authorization": f"Bearer {os.environ['ZAVUDEV_API_KEY']}", "Content-Type": "application/json", }, json={ "to": "+14155551234", "channel": "whatsapp", "text": "Hi! First message via Zavu.", }, timeout=30, ) response.raise_for_status() message = response.json()["message"] print(message["id"], message["status"])
Free messages vs templates
The 24-hour window is central to the Cloud API:
- Within 24h of customer replying: send anything (text, media, buttons)
- Outside 24h: only approved templates
Sending a template
TypeScriptawait zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "template", content: { templateId: "tpl_order_confirmed", templateVariables: { "1": "John", "2": "12345", "3": "$89.90" } } })
Template categories (US):
- Utility (transactional) — confirmations, reminders — $0.015
- Authentication (OTP) — codes — $0.005
- Marketing (promotional) — offers — $0.025
Rich media
TypeScript// Image await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "image", text: "Check out our new product!", content: { mediaUrl: "https://example.com/product.jpg" } }) // Document (PDF) await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "document", content: { mediaUrl: "https://example.com/invoice.pdf", filename: "invoice.pdf" } }) // Interactive buttons await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "buttons", text: "How can we help?", content: { buttons: [ { id: "buy", title: "I want to buy" }, { id: "question", title: "Ask a question" }, { id: "tracking", title: "Track order" } ] } })
Receiving messages (webhooks)
Configure an HTTPS endpoint in the Zavu Dashboard. Every incoming message generates a POST:
TypeScript// app/api/whatsapp-webhook/route.ts (Next.js) import crypto from "node:crypto" // X-Zavu-Signature: t=<seconds>,v2=<hex> (v1=<hex> on older webhooks) // v2 = HMAC_SHA256(secret, "{t}.{body}"), v1 = HMAC_SHA256(secret, body) function verifySignature(rawBody: string, header: string | null): boolean { const secret = process.env.ZAVU_WEBHOOK_SECRET if (!header || !secret) return false const parts: Record<string, string> = {} for (const piece of header.split(",")) { const i = piece.indexOf("=") if (i > 0) parts[piece.slice(0, i)] = piece.slice(i + 1) } const t = Number(parts.t) if (!Number.isFinite(t)) return false const age = Math.floor(Date.now() / 1000) - t if (age > 300 || age < -60) return false const received = parts.v2 ?? parts.v1 if (!received) return false const signed = parts.v2 ?: rawBody const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex") return expected.length === received.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received)) } export async function POST(req: Request) { // Verify the signature over the raw body, before parsing it const rawBody = await req.text() if (!verifySignature(rawBody, req.headers.get("x-zavu-signature"))) { return new Response("Unauthorized", { status: 401 }) } const event = JSON.parse(rawBody) switch (event.type) { case "message.inbound": console.log(${t}.${rawBody}Customer${event.data.from}: ${event.data.text}) break case "message.delivered": console.log(Message${event.data.messageId} delivered) break case "message.read": console.log(Message${event.data.messageId} read) break } return new Response("ok") }
Common errors
131056 - Number not registered: number isn't enabled in WhatsApp Business. Check Meta Business Suite.
131005 - Access denied: token wrong or expired. Use System User token (permanent) in production.
132000 - Template not approved: template still in review. Wait for approval or use free text within the 24h window.
Message doesn't arrive: destination may not have WhatsApp, or blocked your number. Check via message.failed webhook.
Webhook doesn't respond in 2s: Meta retries up to 3 times. Structure your endpoint to respond fast and process async.
WhatsApp Cloud API costs (US, 2026)
Meta charges per initiated 24h conversation, not per message:
| Category | Meta cost |
|---|---|
| Utility (transactional) | ~$0.015 |
| Authentication (OTP) | ~$0.005 |
| Marketing | ~$0.025 |
| Service (customer initiates) | Free |
BSPs add platform cost. Zavu passes Meta's cost without markup — you see full pricing before starting.
Related resources
- How WhatsApp Business works
- WhatsApp Business auto-reply
- Build a WhatsApp AI agent with FastAPI
- Technical documentation
- Zavu vs Twilio for WhatsApp
Conclusion
WhatsApp Cloud API trades the phone app for a programmable REST endpoint. You can go direct to Meta (more work, more control) or use an official BSP like Zavu (simpler, no token/template/migration headaches). The API gives you everything the app lacks: multi-agent, CRM integration, template automation, webhooks and rich media. Start with the tutorial above — in 30 minutes you send your first message.