--- title: WhatsApp Cloud API: Tutorial Completo para Desenvolvedores (2026) description: Tutorial passo a passo da WhatsApp Cloud API: setup, autenticação, envio de mensagens, templates, webhooks e código em Python e Node.js. date: 2026-05-17 author: Victor Villalobos locale: pt source: https://www.zavu.dev/pt/blog/whatsapp-cloud-api-tutorial tags: WhatsApp, API, Tutorial, Desenvolvedores --- # WhatsApp Cloud API: Tutorial Completo para Desenvolvedores (2026) 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 Meta | Você hospeda | | Setup em horas | Setup em semanas | | Sem servidor para manter | VPS + Docker + manutenção | | Mesma performance | Mais complexa | | Recomendada para 99% dos casos | Apenas casos enterprise específicos | **Você não precisa lidar diretamente com a Cloud API.** Provedores oficiais (BSPs) como [Zavu](https://www.zavu.dev/pt) abstraem a complexidade. Mas é importante entender o que tem por baixo. ## Pré-requisitos Antes de começar: 1. Conta **Meta Business Manager** (gratuita, criar em [business.facebook.com](https://business.facebook.com)) 2. Um **número de telefone** que **não esteja** ativo no app WhatsApp normal nem WhatsApp Business 3. Um **website** verificado para o negócio (obrigatório para verificação do business) 4. 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: 1. Cadastre seu **App** no developers.facebook.com 2. Adicione o produto **WhatsApp** 3. Ative uma conta WhatsApp Business e adicione o número 4. Gere um **token temporário** (24h) para testes ou um permanente via System User 5. Faça a primeira request: ```bash curl -X POST \ "https://graph.facebook.com/v18.0//messages" \ -H "Authorization: Bearer " \ -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](https://dashboard.zavu.dev) — 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: | Categoria | Custo 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](/pt/pricing) antes de começar. ## Recursos relacionados - [WhatsApp Business: como funciona](/pt/blog/whatsapp-business-como-funciona) - [Mensagem automática no WhatsApp Business](/pt/blog/mensagem-automatica-whatsapp-business) - [Construa um agente de IA para WhatsApp com FastAPI](/pt/blog/whatsapp-ai-agents-fastapi) - [Documentação técnica Zavu](https://docs.zavu.dev/guides/whatsapp/overview) - [Zavu vs Twilio para WhatsApp](/pt/vs/twilio) ## 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.