--- title: WhatsApp Cloud API: Complete Developer Tutorial (2026) description: Step-by-step WhatsApp Cloud API tutorial: setup, auth, sending messages, templates, webhooks and code in Python and Node.js. date: 2026-05-17 author: Victor Villalobos locale: en source: https://www.zavu.dev/en/blog/whatsapp-cloud-api-tutorial tags: WhatsApp, API, Tutorial, Developers --- # WhatsApp Cloud API: Complete Developer Tutorial (2026) > **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](https://www.zavu.dev/docs/sdks/overview). 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](https://www.zavu.dev/en) abstract the complexity. But understanding what's underneath is useful. ## Prerequisites Before you start: 1. **Meta Business Manager** account (free, create at [business.facebook.com](https://business.facebook.com)) 2. A **phone number** that is **NOT** active on regular WhatsApp or WhatsApp Business app 3. A **verified website** for the business 4. A server with HTTPS for webhooks (Vercel, AWS, Cloudflare Workers) ## Path 1: Direct via Meta (complex) If you want to go direct via Meta without a BSP: 1. Register your **App** at developers.facebook.com 2. Add the **WhatsApp** product 3. Enable a WhatsApp Business account and add the number 4. Generate a **temporary token** (24h) for testing or a permanent one via System User 5. First request: ```bash curl -X POST \ "https://graph.facebook.com/v18.0//messages" \ -H "Authorization: Bearer " \ -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](https://dashboard.zavu.dev) — 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. ```bash # Node.js npm install @zavudev/sdk ``` ```bash # Python (plain HTTP, no Zavu package needed) pip install requests ``` ### 4. Send first message **Node.js / TypeScript:** ```typescript import 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):** ```python import 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 ```typescript await 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=,v2= (v1= 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 = {} 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 ? `${t}.${rawBody}` : 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(`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](/en/pricing) before starting. ## Related resources - [How WhatsApp Business works](/en/blog/whatsapp-business-como-funciona) - [WhatsApp Business auto-reply](/en/blog/mensagem-automatica-whatsapp-business) - [Build a WhatsApp AI agent with FastAPI](/en/blog/whatsapp-ai-agents-fastapi) - [Technical documentation](https://www.zavu.dev/docs/guides/whatsapp/overview) - [Zavu vs Twilio for WhatsApp](/en/vs/twilio) ## 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.