WhatsApp Cloud API em 2026: guia completo (com um caso real)

Se você quer construir um bot ou automação séria no WhatsApp, existe um jeito certo e vários jeitos errados. O jeito certo é a WhatsApp Cloud API, a solução oficial da Meta. Os errados são as bibliotecas não oficiais que "hackeiam" o WhatsApp Web e podem custar o seu número.

Este guia explica como a Cloud API funciona, quanto custa de verdade em 2026 e o que aprendemos operando o Reth, um bot de figurinhas que atende mais de 50 mil pessoas nela.

O que é a WhatsApp Cloud API?

É a API oficial da Meta para empresas e desenvolvedores integrarem com o WhatsApp. A infraestrutura roda nos servidores da própria Meta (por isso "Cloud"): você só precisa de um servidor para receber webhooks e disparar requisições HTTP.

Comparada às soluções não oficiais (Baileys, Venom, wppconnect e afins):

Quanto custa em 2026 (a parte que todo mundo erra)

O modelo de cobrança mudou ao longo dos anos e muito conteúdo na internet está desatualizado. O resumo atual:

• Conversas de serviço são gratuitas e ilimitadas desde novembro de 2024. Ou seja: se o usuário te chama primeiro e você responde dentro da janela de 24 horas, você não paga nada, em qualquer volume.
• O que se paga são templates: mensagens de marketing, utilidade e autenticação que VOCÊ inicia fora da janela. A cobrança é por mensagem entregue, com preço por categoria e país.

Isso muda o desenho do produto. O Reth, por exemplo, é 100% reativo: o usuário sempre manda mensagem primeiro (uma foto pra virar figurinha), então o custo de mensageria do bot é essencialmente zero, mesmo com dezenas de milhares de usuários ativos. Se o seu caso de uso é "responder o usuário", a Cloud API é de graça.

A regra nova de 2026: nada de IA genérica

Em 15 de janeiro de 2026, a Meta atualizou os termos da API e baniu assistentes de IA de uso geral (o número do ChatGPT no WhatsApp foi desativado nessa leva). Bots precisam ter propósito específico: atendimento, um serviço, uma ferramenta.

Na prática, para quem desenvolve:

• Bot de nicho com função clara: liberado
• "ChatGPT no WhatsApp" e assistentes genéricos: proibidos
• Usar IA nos bastidores (entender linguagem natural, rotear intenção): liberado, desde que o produto tenha escopo definido

O Reth viveu essa transição na pele: nasceu como assistente de IA e virou bot de figurinhas. A IA continua no produto, mas como camada de interpretação, não como produto final. Contamos essa história em detalhe neste post.

Arquitetura básica

Usuário → WhatsApp → webhook (seu servidor) → sua lógica → POST na Graph API → usuário

Recebendo mensagens: a Meta envia um POST no seu webhook a cada mensagem. Você precisa responder 200 rápido (processe em fila, não inline).

Enviando mensagens: requisições HTTP na Graph API com o token da sua conta business.

Enviando uma mensagem de texto

const response = await fetch(
  `https://graph.facebook.com/v22.0/${PHONE_NUMBER_ID}/messages`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      messaging_product: 'whatsapp',
      to: '5511999999999',
      type: 'text',
      text: { body: 'Olá! Esta é uma mensagem via Cloud API.' },
    }),
  },
);

(Confira a versão atual da Graph API na doc da Meta; ela avança a cada poucos meses e as antigas são aposentadas.)

Botões de resposta rápida

{
  messaging_product: 'whatsapp',
  to: '5511999999999',
  type: 'interactive',
  interactive: {
    type: 'button',
    body: { text: 'Sua figurinha ficou pronta! Quer fazer outra?' },
    action: {
      buttons: [
        { type: 'reply', reply: { id: 'again', title: 'Criar outra 🎨' } },
        { type: 'reply', reply: { id: 'help', title: 'Ver comandos' } },
      ],
    },
  },
}

Lições de produção (caso Reth)

Coisas que a documentação não conta e a gente aprendeu operando em escala:

1. Fila antes de tudo. Webhook da Meta reenvia se você demorar. Recebemos, jogamos numa fila (Redis) e respondemos 200 na hora. O processamento pesado (converter vídeo em figurinha, por exemplo) roda nos workers.

2. A janela de 24h molda o produto. Fora dela, só template pago. Então todo fluxo do Reth é desenhado pra acontecer dentro da conversa que o usuário iniciou. Se você precisa "acordar" o usuário depois, orce os templates.

3. Mídia tem prazo. URLs de mídia recebidas expiram. Baixe na hora e processe do seu lado.

4. Rate limits existem e mordem. Controle a taxa de envio por número. No Reth, limitamos figurinhas por minuto por usuário também, senão um único grupo de amigos animados derruba a fila.

5. Flows são subestimados. WhatsApp Flows (formulários nativos dentro do chat) convertem muito melhor que link externo. Usamos pra doações via PIX e pra central de ajuda.

6. Migrar de biblioteca não oficial vale a pena. O Reth rodou Baileys no passado: instabilidade semanal e medo constante de ban. Depois da migração pra Cloud API, o uptime virou problema resolvido. O custo (zero, no nosso fluxo) foi o menor dos motivos.

Como começar

1. Crie uma conta em developers.facebook.com
2. Crie um app do tipo Business e adicione o produto "WhatsApp"
3. Use o número de teste gratuito pra desenvolver
4. Configure o webhook (URL pública + verify token)
5. Envie a primeira mensagem pelo painel e responda via API
6. Quando estiver pronto, conecte um número real e verifique o business

Vale a pena?

Se o seu bot responde usuários que chegam até ele: sim, sem ressalvas. É grátis nesse fluxo, estável e à prova de banimento. Se o seu modelo depende de disparo em massa, faça a conta dos templates antes (e cuidado com as políticas de spam, a Meta bane conta business também).

Quer ver a Cloud API em ação? O Reth roda inteiro nela: manda um oi e crie uma figurinha.

---

Dúvida técnica? Entra no grupo e pergunta, a gente gosta desse assunto.