API WhatsApp: O Guia Completo para Desenvolvedores (2026)

Se você é desenvolvedor procurando "API WhatsApp", existem três caminhos: a WhatsApp Cloud API oficial da Meta, a WhatsApp Business API via BSP (provedor oficial) e as APIs não oficiais (que você deveria evitar). Este guia explica cada uma, quando usar, e mostra código real em Python, Node.js e cURL para o caminho recomendado.

As 3 APIs do WhatsApp em 2026

1. WhatsApp Cloud API (oficial Meta)

• Hospedada pela Meta
• Acesso direto via Graph API
• Você cuida de tokens, templates, webhooks
• Boa para: equipes com bom time de DevOps

2. WhatsApp Business API via BSP (recomendado)

• BSPs oficiais como Zavu, Twilio, MessageBird
• Abstraem a complexidade (tokens, retries, templates)
• SDK oficial em várias linguagens
• Bom para: 99% dos casos

3. APIs não oficiais (não use)

• Bibliotecas que fazem reverse engineering do WhatsApp Web
• Funcionam até a Meta bloquear
• Sem suporte, sem garantia, sem selo verde
• Pode banir seu número permanentemente

Como começar com a API WhatsApp em 5 minutos

Caminho mais simples: BSP oficial. Aqui está com Zavu:

1. Conta grátis

Crie em zavu.dev. Sem cartão de crédito.

2. Conectar Meta Business

No dashboard, Add WhatsApp Sender → OAuth com Meta → autorize Zavu. Demora 5 minutos.

3. Instalar SDK

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

# Python
pip install zavudev

# Ruby
gem install zavudev

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

4. Enviar primeira mensagem

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: "+5511999998888",
  channel: "whatsapp",
  text: "Olá! Primeira mensagem 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="+5511999998888",
    channel="whatsapp",
    text="Olá! Primeira mensagem via API."
)

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

cURL:

bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer $ZAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999998888",
    "channel": "whatsapp",
    "text": "Olá!"
  }'

Resposta:

json
{
  "message": {
    "id": "msg_01HXY...",
    "status": "queued",
    "channel": "whatsapp",
    "to": "+5511999998888"
  }
}

Tipos de mensagem que a API WhatsApp aceita

Texto

typescript
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  text: "Pedido confirmado! ID: #12345"
})

Mídia (imagem, vídeo, documento)

typescript
// Imagem
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "image",
  text: "Foto do produto",
  content: { mediaUrl: "https://exemplo.com/img.jpg" }
})

// PDF
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "document",
  content: {
    mediaUrl: "https://exemplo.com/nota-fiscal.pdf",
    filename: "nota-fiscal.pdf"
  }
})

Botões interativos

typescript
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "buttons",
  text: "Como posso te ajudar?",
  content: {
    buttons: [
      { id: "rastreio", title: "Rastrear pedido" },
      { id: "trocas", title: "Política de trocas" },
      { id: "humano", title: "Falar com atendente" }
    ]
  }
})

Lista (até 10 opções)

typescript
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "list",
  text: "Escolha um produto:",
  content: {
    listButton: "Ver produtos",
    sections: [{
      title: "Mais vendidos",
      rows: [
        { id: "p1", title: "Produto A", description: "R$ 99" },
        { id: "p2", title: "Produto B", description: "R$ 149" }
      ]
    }]
  }
})

Template (mensagem fora da janela de 24h)

typescript
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "template",
  content: {
    templateId: "tpl_pedido_confirmado",
    templateVariables: { "1": "João", "2": "12345" }
  }
})

Janela de 24 horas: a regra mais importante

A Meta tem uma regra rígida:

• Dentro de 24h depois do cliente te responder: você pode mandar qualquer tipo de mensagem (texto livre, mídia, botões).
• Fora de 24h: você só pode mandar template aprovado.

Por isso é essencial criar templates antes de precisar:

No dashboard Zavu, Templates → Create

Escolha categoria (Utility, Marketing, Authentication)

Envie para aprovação Meta (24-48h)

Use no código:

typescript
templateId: "tpl_aprovado"

Recebendo mensagens (webhooks)

Configure URL de webhook no dashboard. A cada mensagem recebida:

typescript
// Endpoint Next.js
export async function POST(req: Request) {
  const event = await req.json()

  if (event.type === "message.inbound") {
    console.log("Cliente:", event.message.from)
    console.log("Texto:", event.message.text)

    // Responder
    await zavu.messages.send({
      to: event.message.from,
      channel: "whatsapp",
      text: "Recebi! Em breve respondo."
    })
  }

  return new Response("ok")
}

Eventos disponíveis:

• message.inbound — cliente mandou mensagem
• message.delivered — mensagem entregue
• message.read — cliente leu
• message.failed — falhou (motivo no payload)
• conversation.new — primeira conversa com esse cliente
• template.status_changed — template aprovado/rejeitado

Preços da API WhatsApp no Brasil

A Meta cobra por conversa de 24h, não por mensagem:

Categoria	Preço Brasil

Marketing	R$ 0,18
Utility (transacional)	R$ 0,07
Authentication (OTP)	R$ 0,04
Service (cliente inicia)	R$ 0,00

BSPs cobram em cima:

• Zavu: R$ 0 de markup
• Twilio: 5-20% markup
• MessageBird: R$ 3.000 setup + plataforma

Cálculo completo de preços.

Requisitos para usar a API WhatsApp

Meta Business Manager verificado (gratuito)

Número de telefone que não esteja em outro WhatsApp

Website verificado para o negócio

Templates aprovados (para mandar mensagens iniciadas por você)

Política de privacidade publicada

(Brasil) Cadastro no CNPJ ou MEI

Erros comuns e soluções

Erro 131005 - Access denied: token inválido ou expirado. Em produção, use System User token (permanente).Erro 131056 - Number not registered: número não está habilitado na conta WhatsApp Business. Verifique no Meta Business Suite.Erro 132000 - Template not approved: template ainda em revisão. Aguarde ou use texto livre se estiver na janela de 24h.Erro 470 - Re-engagement required: passou da janela de 24h. Use template para reabrir.Webhook não chama: URL precisa ser HTTPS válido e responder 200 em < 2s. Use Cloudflare Workers ou Vercel para garantia.Mensagem "queued" e não entrega: cliente pode não ter WhatsApp instalado, ter te bloqueado ou o número ser inválido. Cheque pelo webhook message.failed.

Diferenças entre Cloud API direta e via BSP

Cloud API direta	Via Zavu (BSP)

Setup tempo	1-2 semanas	30 min
Verificação business	Você faz tudo	Zavu te guia
Renovação de tokens	Você gerencia	Automática
Aprovação de templates	Manual no Business Suite	API + dashboard
Webhooks com assinatura	Você implementa	SDK valida
Multi-canal (SMS + WhatsApp)	Só WhatsApp	Tudo unificado
Retries automáticos	Você implementa	Incluído
SDK oficial	Não (só REST)	Sim (TS, Py, Go, Ruby, PHP)

Para 99% dos casos, ir via BSP economiza semanas de trabalho.

Recursos relacionados

• WhatsApp Cloud API: tutorial passo a passo
• WhatsApp Business API preços Brasil
• WhatsApp Business: como funciona
• Documentação técnica completa
• Agentes de IA para WhatsApp

Conclusão

A API WhatsApp em 2026 dá controle total sobre a comunicação com seus clientes — desde notificações automáticas até agentes de IA que atendem 24h. O caminho mais rápido e seguro é usar um BSP oficial como Zavu: 5 minutos para começar, SDK em sua linguagem, preço sem markup e suporte real. Comece pelo plano gratuito de 2.000 mensagens — e escale quando o volume crescer.