WhatsApp Cloud API: endpoint, tokens, webhooks e limites

O que é a Cloud API

A Meta define a Cloud API como a forma de enviar mensagens e fazer ligações no WhatsApp de maneira programática. Ela cobre três frentes:

• Mensagens — texto, mídia, botões, listas, templates e os eventos de entrega e leitura.
• Ligações — fazer e receber chamadas de voz pelo WhatsApp, disponível desde julho de 2025.
• Grupos — criar e administrar grupos pela API, desde outubro de 2025.

Ela faz parte da WhatsApp Business Platform, ao lado da Business Management API (que administra contas, números e templates) e da Marketing Messages API. A visão de negócio — quem pode usar, como ter acesso e o que diferencia a API oficial das integrações não oficiais — está em o que é a API oficial do WhatsApp.

“Cloud” quer dizer que a Meta hospeda. Até 2025 existia também a On-Premises API, que a empresa ou o provedor rodava no próprio servidor. Ela parou de ganhar recursos novos em janeiro de 2024, deixou de aceitar números novos em julho de 2024 e parou de enviar mensagens em 23 de outubro de 2025. Ao anunciar o fim, a Meta citou para a Cloud API até 1.000 mensagens por segundo, 99,9% de disponibilidade e conformidade com a LGPD.

Como funciona uma chamada

A plataforma é construída sobre a Graph API, a mesma base das outras APIs da Meta. Enviar uma mensagem é um POST autenticado com um token no endpoint de mensagens do número:

curl -X POST "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Seu pedido saiu para entrega." }
  }'

O texto livre do exemplo só é aceito com a janela de atendimento aberta, isto é, nas 24 horas seguintes à última mensagem do cliente. Fora dela, o corpo precisa ser um template aprovado. A resposta do envio traz o identificador da mensagem; se ela foi entregue, lida ou falhou chega depois, por webhook.

Ativos, identificadores e tokens

Antes da primeira chamada, a Meta exige um conjunto de ativos. Os nomes estão mudando: desde setembro de 2026 a antiga conta WhatsApp Business (WABA) está sendo dividida em duas, e o painel pode mostrar o nome novo ou o antigo até o fim da migração. IDs, endpoints e tokens continuam valendo.

O acesso é por token. Quem integra para si mesmo usa o token de um usuário do sistema do portfólio; um Tech Provider usa o token de integração gerado no Embedded Signup do cliente. O token do usuário comum expira em poucas horas e serve só para o primeiro teste. As permissões são whatsapp_business_messaging, whatsapp_business_management e business_management.

Webhooks: como as mensagens chegam

Tudo o que o cliente envia e todo status de entrega chegam por webhook — não há outra forma de receber, e não existe API para buscar eventos antigos. O que a Meta exige do endpoint:

• Verificação — ao cadastrar a URL, a Meta faz um GET com hub.challenge, e o endpoint responde 200 devolvendo esse valor.
• Assinatura — cada evento chega em POST com o cabeçalho X-Hub-Signature-256, um HMAC-SHA256 do corpo calculado com o segredo do aplicativo. Valide antes de processar.
• TLS válido — certificado autoassinado não é aceito.
• Retentativa — evento sem resposta 200 é reenviado por até 7 dias, então o mesmo evento pode chegar mais de uma vez. Deduplique.
• Volume — corpo de até 3 MB, com vários eventos por entrega. A Meta pede que o servidor aguente cerca de três vezes o tráfego de saída, porque cada mensagem enviada gera vários status.

Desde abril de 2026 os webhooks também trazem o BSUID, um identificador do cliente por portfólio. Quando a pessoa adota um nome de usuário no WhatsApp, o telefone dela pode deixar de vir no evento; a Meta trata o suporte ao BSUID como obrigatório para integrações. Sistema que identifica o contato só pelo telefone precisa se preparar.

Limites de envio

A Cloud API tem dois limites diferentes, que costumam ser confundidos:

O limite de mensagens mudou em 7 de outubro de 2025: passou a ser calculado por portfólio, e não mais por número; o primeiro degrau acima do inicial passou a ser 2.000; a subida, quando a empresa usa pelo menos metade do limite com qualidade alta, passou a acontecer em até 6 horas; e a queda de qualidade deixou de rebaixar o nível já conquistado. Qualidade ruim agora pesa nos templates, que podem ser pausados, e trava a subida. Muito conteúdo em português ainda descreve a regra antiga, que contava conversas por dia em cada número.

Como esses limites aparecem num fluxo automatizado — e por que a automação precisa de fila com nova tentativa — está em automação de WhatsApp por API e webhooks.

Versões da Graph API

Cada chamada leva a versão no caminho. A mais recente é a v26.0, de julho de 2026; a v25.0, de fevereiro de 2026, é suportada até julho de 2028, e a v24.0 até fevereiro de 2028. Fixar a versão evita mudança de comportamento sem aviso; a troca vale ser planejada com a lista de mudanças da Meta, e não feita no dia em que a versão expira.

O que mudou entre 2025 e 2026

A Cloud API mudou mais nesses dois anos do que nos anteriores. Se o material que você está lendo não cita estas mudanças, ele é anterior a elas:

Também está em andamento o fim do PIN de verificação em duas etapas para números da Cloud API, e as versões 2 e 3 do Embedded Signup deixam de funcionar em 15 de outubro de 2026.

Como começar

Há dois caminhos, e a diferença é quem monta e mantém a infraestrutura.

Direto pela Meta, o roteiro é: criar um aplicativo do tipo Business no painel de desenvolvedores com o caso de uso de WhatsApp, enviar a primeira mensagem pelo número de teste que a Meta gera (com limites reduzidos e sem exigir meio de pagamento), depois adicionar o número real, registrá-lo, gerar o token de usuário do sistema, configurar o webhook e cadastrar o meio de pagamento.

Por um provedor, o número é conectado pela conta Meta do próprio cliente e continua dele. No CRPRO Hub, por exemplo, você cria uma chave de API, conecta o número — com coexistência, se ele já está no aplicativo — e envia pela API do Hub, com webhook assinado. O caminho completo está em como conectar um número e no início rápido.

Perguntas frequentes