Voltar ao Blog
WhatsAppAPITutorialDesenvolvedores

WhatsApp Cloud API: Tutorial Completo para Desenvolvedores (2026)

Tutorial passo a passo da WhatsApp Cloud API: setup, autenticação, envio de mensagens, templates, webhooks e código em Python e Node.js.

Escrito por: Victor VillalobosRevisado por: Jennifer Villalobos17 de maio de 202612 min de leitura
A WhatsApp Cloud API é a API oficial da Meta para mandar e receber mensagens no WhatsApp Business, hospedada e mantida pela própria Meta (não exige hospedar nada por sua conta). Este tutorial mostra como começar do zero até a primeira mensagem enviada, com código real em Python e Node.js.

O que é a WhatsApp Cloud API

A Cloud API substituiu a antiga "On-Premises API" em 2022. As diferenças:

Cloud API (atual)On-Premises (legado)
Hospedada pela MetaVocê hospeda
Setup em horasSetup em semanas
Sem servidor para manterVPS + Docker + manutenção
Mesma performanceMais complexa
Recomendada para 99% dos casosApenas casos enterprise específicos
Você não precisa lidar diretamente com a Cloud API. Provedores oficiais (BSPs) como Zavu abstraem a complexidade. Mas é importante entender o que tem por baixo.

Pré-requisitos

Antes de começar:

  • Conta Meta Business Manager (gratuita, criar em business.facebook.com)
  • Um número de telefone que não esteja ativo no app WhatsApp normal nem WhatsApp Business
  • Um website verificado para o negócio (obrigatório para verificação do business)
  • Um servidor com HTTPS para receber webhooks (Vercel, AWS, Cloudflare Workers, etc.)

    • Caminho 1: Direto pela Meta (complexo)

    Se você quiser ir direto pela Meta, sem BSP:

  • Cadastre seu App no developers.facebook.com
  • Adicione o produto WhatsApp
  • Ative uma conta WhatsApp Business e adicione o número
  • Gere um token temporário (24h) para testes ou um permanente via System User
  • Faça a primeira request:
    • bash
    curl -X POST \
  "https://graph.facebook.com/v18.0/<PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "template",
    "template": { "name": "hello_world", "language": { "code": "en_US" } }
  }'
    Esse caminho funciona, mas você ainda precisa:
    • Aprovar templates manualmente no Meta Business Suite
    • Lidar com renovação de tokens
    • Implementar webhooks com verificação de assinatura
    • Tratar erros e retries
    • Migrar de número se a Meta limitar

    Caminho 2: Via BSP oficial (recomendado)

    Provedores oficiais resolvem 90% da complexidade. Aqui está como funciona com Zavu:

    1. Crie conta gratuita

    zavu.dev/pt/signup — sem cartão de crédito.

    2. Conecte sua conta Meta Business

    No dashboard, clique em Add WhatsApp Sender e siga o fluxo de OAuth. Você é redirecionado para o Meta, autoriza Zavu como BSP, e volta. Leva 5 minutos.

    3. Instale o SDK

    bash
    # Node.js
npm install @zavudev/sdk
    bash
    # Python
pip install zavudev

    4. Envie a primeira mensagem

    Node.js / TypeScript:
    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á! Esta é a primeira mensagem via Zavu 🎉"
})

console.log(result.message.id)  // msg_xxx
console.log(result.message.status)  // queued
    Python:
    python
    from zavudev import Zavu

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

result = zavu.messages.send(
    to="+5511999998888",
    channel="whatsapp",
    text="Olá! Esta é a primeira mensagem via Zavu 🎉"
)

print(result.message.id)
print(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á!"
  }'

    Mensagens livres vs templates

    A janela de 24 horas é central na Cloud API:

    • Dentro de 24h depois do cliente te mandar mensagem: você pode enviar qualquer coisa (texto, mídia, botões)
    • Fora de 24h: você só pode enviar templates aprovados pela Meta

    Enviando template

    typescript
    await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "template",
  content: {
    templateId: "tpl_pedido_confirmado",
    templateVariables: {
      "1": "João",          // {{1}} no body
      "2": "12345",         // {{2}}
      "3": "R$ 89,90"       // {{3}}
    }
  }
})

    Templates precisam de aprovação Meta (24-48h). Categorias:

    • Utility (transacional) — confirmação, lembrete, status — ~R$ 0,07
    • Authentication (OTP) — códigos — ~R$ 0,04
    • Marketing (promocional) — ofertas — ~R$ 0,18

    Mídia rica

    typescript
    // Imagem
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "image",
  text: "Confira nosso novo produto!",
  content: {
    mediaUrl: "https://example.com/produto.jpg"
  }
})

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

// Botões interativos
await zavu.messages.send({
  to: "+5511999998888",
  channel: "whatsapp",
  messageType: "buttons",
  text: "Como podemos te ajudar?",
  content: {
    buttons: [
      { id: "comprar", title: "Quero comprar" },
      { id: "duvida", title: "Tirar dúvida" },
      { id: "rastreio", title: "Rastrear pedido" }
    ]
  }
})

    Recebendo mensagens (webhooks)

    Configure um endpoint HTTPS no Zavu Dashboard. A cada mensagem recebida, Zavu manda um POST:

    typescript
    // app/api/whatsapp-webhook/route.ts (Next.js)
export async function POST(req: Request) {
  const event = await req.json()

  // Verifique a assinatura para segurança
  const signature = req.headers.get("x-zavu-signature")
  if (!verifySignature(signature, event)) {
    return new Response("Unauthorized", { status: 401 })
  }

  switch (event.type) {
    case "message.inbound":
      console.log(Cliente ${event.message.from} disse: ${event.message.text})
      // Responder ou processar
      break
    case "message.delivered":
      console.log(Mensagem ${event.message.id} entregue)
      break
    case "message.read":
      console.log(Mensagem ${event.message.id} lida)
      break
  }

  return new Response("ok")
}

    Erros comuns

    1. 131056 — Number not registered: o número não está habilitado no WhatsApp Business. Verifique no Meta Business Suite.2. 131005 — Access denied: o token está errado ou expirou. Use System User token (permanente) em produção.3. 132000 — Template not approved: você tentou usar template ainda em revisão. Aguarde aprovação ou use texto livre dentro da janela de 24h.4. Mensagem não chega: o número de destino pode não ter WhatsApp, ou bloqueou seu número. Verifique pelo webhook message.failed.5. Webhook não responde em 2 segundos: a Meta tenta reenviar até 3 vezes. Estruture seu endpoint para responder rápido e processar async.

    Custos da WhatsApp Cloud API

    A Meta cobra por conversa de 24h iniciada, não por mensagem. Preços Brasil 2026:

    CategoriaCusto Meta
    Utility (transacional)~R$ 0,07
    Authentication (OTP)~R$ 0,04
    Marketing~R$ 0,18
    Service (cliente inicia)Gratuito
    BSPs adicionam custo de plataforma. Zavu repassa o custo da Meta sem markup — você vê os preços completos antes de começar.

    Recursos relacionados

    Conclusão

    A WhatsApp Cloud API troca o app de celular por um endpoint REST programável. Você pode ir direto pela Meta (mais trabalho, mais controle) ou usar um BSP oficial como Zavu (mais simples, sem cuidar de tokens, templates e migrações). A API te dá tudo que o app não tem: múltiplos atendentes, integração com CRM, automação de templates, webhooks e mídia rica. Comece com o tutorial acima — em 30 minutos você manda a primeira mensagem.

    Precisa de ajuda? Contate-nos ou junte-se à nossa comunidade Discord para suporte.

    Follow us on social media

    @zavudevZavuzavudevDiscord Community

    Pronto para começar?

    Comece a construir gratuitamente ou agende uma chamada para discutir seu caso de uso específico.

    Começar GratuitamenteAgendar Chamada
    WhatsApp Cloud API: Tutorial Completo 2026 | Zavu Blog