> 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.
If you're a developer searching for "WhatsApp API", there are three paths: WhatsApp Cloud API direct from Meta, WhatsApp Business API via BSP (official provider) and unofficial APIs (avoid). This guide covers each, when to use which, and shows real code in Python, Node.js and cURL for the recommended path.
The 3 WhatsApp APIs in 2026
1. WhatsApp Cloud API (Meta official)
- Hosted by Meta
- Direct Graph API access
- You handle tokens, templates, webhooks
- Good for: teams with strong DevOps
2. WhatsApp Business API via BSP (recommended)
- Official BSPs like Zavu, Twilio, MessageBird
- Abstract complexity (tokens, retries, templates)
- An official SDK or a plain REST API
- Good for: 99% of cases
3. Unofficial APIs (don't use)
- Libraries reverse-engineering WhatsApp Web
- Work until Meta blocks them
- No support, no warranty, no green badge
- Can permanently ban your number
How to start with WhatsApp API in 5 minutes
Easiest path: official BSP. Here with Zavu:
1. Free account
Create at zavu.dev. No credit card.
2. Connect Meta Business
In the dashboard, Add WhatsApp Sender → OAuth with Meta → authorize Zavu as BSP. ~5 min.
3. Install the SDK (TypeScript) or use the REST API
Zavu's official SDK is TypeScript. Any other language calls the REST API directly: https://api.zavu.dev, an Authorization: Bearer header and a JSON body.
terminal# Node.js / TypeScript npm install @zavudev/sdk # Python (plain HTTP, no Zavu package needed) pip install requests
4. Send first message
Node.js:
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 API." }) 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 API.", }, timeout=30, ) response.raise_for_status() message = response.json()["message"] print(message["id"], message["status"])
cURL:
terminalcurl -X POST https://api.zavu.dev/v1/messages \ -H "Authorization: Bearer $ZAVUDEV_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+14155551234", "channel": "whatsapp", "text": "Hi!" }'
Response:
JSON{ "message": { "id": "msg_01HXY...", "status": "queued", "channel": "whatsapp", "to": "+14155551234" } }
Message types the API accepts
Text
TypeScriptawait zavu.messages.send({ to: "+14155551234", channel: "whatsapp", text: "Order confirmed! ID: #12345" })
Media (image, video, document)
TypeScript// Image await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "image", text: "Product photo", content: { mediaUrl: "https://example.com/img.jpg" } }) // PDF await zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "document", content: { mediaUrl: "https://example.com/invoice.pdf", filename: "invoice.pdf" } })
Interactive buttons
TypeScriptawait zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "buttons", text: "How can I help you?", content: { buttons: [ { id: "tracking", title: "Track order" }, { id: "returns", title: "Return policy" }, { id: "human", title: "Talk to agent" } ] } })
List (up to 10 options)
TypeScriptawait zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "list", text: "Pick a product:", content: { listButton: "View products", sections: [{ title: "Best sellers", rows: [ { id: "p1", title: "Product A", description: "$99" }, { id: "p2", title: "Product B", description: "$149" } ] }] } })
Template (outside 24h window)
TypeScriptawait zavu.messages.send({ to: "+14155551234", channel: "whatsapp", messageType: "template", content: { templateId: "tpl_order_confirmed", templateVariables: { "1": "John", "2": "12345" } } })
The 24-hour window: the most important rule
Meta has a strict rule:
- Within 24h of the customer replying: you can send any type of message (free text, media, buttons).
- Outside 24h: only approved templates.
So it's essential to create templates before you need them:
TypeScripttemplateId: "tpl_approved"
Receiving messages (webhooks)
Configure webhook URL in the dashboard. Every incoming message:
TypeScript// Next.js endpoint export async function POST(req: Request) { const event = await req.json() if (event.type === "message.inbound") { console.log("Customer:", event.data.from) console.log("Text:", event.data.text) // Reply await zavu.messages.send({ to: event.data.from, channel: "whatsapp", text: "Got it! Replying shortly." }) } return new Response("ok") }
Available events:
message.inbound— customer sent messagemessage.delivered— message deliveredmessage.read— customer readmessage.failed— failed (reason in payload)conversation.new— first conversation with this customertemplate.status_changed— template approved/rejected
WhatsApp API pricing in US
Meta charges per 24h conversation, not per message:
| Category | US Price |
|---|---|
| Marketing | $0.025 |
| Utility (transactional) | $0.015 |
| Authentication (OTP) | $0.005 |
| Service (customer initiates) | $0.00 |
BSPs charge on top:
- Zavu: $0 markup
- Twilio: 5-20% markup
- MessageBird: $600 setup + platform
Requirements to use WhatsApp API
Common errors and fixes
Error 131005 - Access denied: invalid or expired token. In production, use System User token (permanent).
Error 131056 - Number not registered: number not enabled in WhatsApp Business account. Verify in Meta Business Suite.
Error 132000 - Template not approved: template still in review. Wait or use free text in 24h window.
Error 470 - Re-engagement required: passed the 24h window. Use template to reopen.
Webhook not called: URL must be valid HTTPS and respond 200 in < 2s. Use Cloudflare Workers or Vercel for reliability.
Message "queued" and not delivering: customer may not have WhatsApp, blocked you, or invalid number. Check via message.failed webhook.
Direct Cloud API vs via BSP
| Cloud API direct | Via Zavu (BSP) | |
|---|---|---|
| Setup time | 1-2 weeks | 30 min |
| Business verification | You do it | Zavu guides |
| Token renewal | You manage | Automatic |
| Template approval | Manual in Business Suite | API + dashboard |
| Signed webhooks | You implement | HMAC-signed, verify with a few lines |
| Multi-channel (SMS + WhatsApp) | WhatsApp only | All unified |
| Automatic retries | You implement | Included |
| Official SDK | No (only REST) | TypeScript, plus REST for any language |
For 99% of cases, going via BSP saves weeks of work.
Related resources
- WhatsApp Cloud API: step-by-step tutorial
- WhatsApp Business API pricing
- How WhatsApp Business works
- Complete technical documentation
- AI agents for WhatsApp
Conclusion
The WhatsApp API in 2026 gives total control over communication with your customers — from automatic notifications to AI agents that answer 24h. Fastest, safest path is using an official BSP like Zavu: 5 minutes to start, a TypeScript SDK and a REST API any language can call, no-markup pricing and real support. Start with the free tier of 2,000 messages — scale when volume grows.