---
title: API WhatsApp: O Guia Completo para Desenvolvedores (2026)
description: Tudo sobre API WhatsApp em 2026: opções (Cloud API, Business API, não oficial), preço, requisitos, exemplos em Python, Node.js e cURL.
date: 2026-05-17
author: Victor Villalobos
locale: pt
source: https://www.zavu.dev/pt/blog/api-whatsapp-guia-completo
tags: WhatsApp, API, Desenvolvedores, Tutorial
---

# 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](https://www.zavu.dev/pt), 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](https://www.zavu.dev/pt). 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:

1. No dashboard Zavu, **Templates** → **Create**
2. Escolha categoria (Utility, Marketing, Authentication)
3. Envie para aprovação Meta (24-48h)
4. 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](/pt/blog/whatsapp-business-api-pricing).

## Requisitos para usar a API WhatsApp

1. **Meta Business Manager** verificado (gratuito)
2. **Número de telefone** que não esteja em outro WhatsApp
3. **Website** verificado para o negócio
4. **Templates** aprovados (para mandar mensagens iniciadas por você)
5. **Política de privacidade** publicada
6. (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](/pt/blog/whatsapp-cloud-api-tutorial)
- [WhatsApp Business API preços Brasil](/pt/blog/whatsapp-business-api-pricing)
- [WhatsApp Business: como funciona](/pt/blog/whatsapp-business-como-funciona)
- [Documentação técnica completa](https://docs.zavu.dev/quickstart)
- [Agentes de IA para WhatsApp](/pt/ai-agents)

## 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](/pt/whatsapp-business-api): 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.