WhatsApp API: The Complete Developer Guide (2026)

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)
• Official SDK in multiple languages
• 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 SDK

terminal
# Node.js / TypeScript
npm install @zavudev/sdk

# Python
pip install zavudev

# Ruby
gem install zavudev

# Go
go get github.com/zavudev/zavudev-go

4. Send first message

Node.js:

TypeScript
import Zavu from "@zavudev/sdk"
const zavu = new Zavu({ apiKey: process.env.ZAVU_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:

Python
from zavudev import Zavu
import os

zavu = Zavu(api_key=os.environ["ZAVU_API_KEY"])

result = zavu.messages.send(
    to="+14155551234",
    channel="whatsapp",
    text="Hi! First message via API."
)

print(result.message.id, result.message.status)

cURL:

terminal
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_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

TypeScript
await 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

TypeScript
await 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)

TypeScript
await 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)

TypeScript
await 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:

TypeScript
templateId: "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.message.from)
    console.log("Text:", event.message.text)

    // Reply
    await zavu.messages.send({
      to: event.message.from,
      channel: "whatsapp",
      text: "Got it! Replying shortly."
    })
  }

  return new Response("ok")
}

Available events:

• message.inbound — customer sent message
• message.delivered — message delivered
• message.read — customer read
• message.failed — failed (reason in payload)
• conversation.new — first conversation with this customer
• template.status_changed — template approved/rejected

WhatsApp API pricing in US

Meta charges per 24h conversation, not per message:

BSPs charge on top:

• Zavu: $0 markup
• Twilio: 5-20% markup
• MessageBird: $600 setup + platform

Full pricing breakdown.

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

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, SDK in your language, no-markup pricing and real support. Start with the free tier of 2,000 messages — scale when volume grows.