Atualizado em 25/10/2026
A WhatsApp Cloud API é a versão da API oficial do WhatsApp hospedada pela própria Meta: você não instala servidor nenhum, só faz chamadas HTTP para a Graph API (graph.facebook.com) e recebe eventos por webhook. Desde 23 de outubro de 2025, com o fim da On-Premises API, ela é o único jeito de rodar a WhatsApp Business Platform. A Meta cobra por mensagem entregue, com preço definido pela categoria da mensagem e pelo país do destinatário.
Este artigo foca na parte técnica da Cloud API: componentes, fluxo de uma mensagem, limites e custo. Para a visão geral de requisitos, comparação com APIs não oficiais e quando a API oficial faz sentido, veja o guia completo da API oficial do WhatsApp.
O que é a WhatsApp Cloud API
A Meta chama de WhatsApp Business Platform o conjunto de APIs que permite a empresas conversar com clientes no WhatsApp a partir de sistemas próprios. A Cloud API é a parte dessa plataforma que envia e recebe mensagens, faz chamadas e gerencia grupos, segundo a visão geral da Cloud API.
“Cloud” aqui quer dizer que a infraestrutura de mensagens roda na Meta. Seu código não guarda sessão, não mantém conexão aberta com o WhatsApp e não depende de um celular ligado. Ele só:
- faz requisições HTTPS autenticadas com um token de acesso;
- recebe requisições da Meta num endpoint de webhook.
Isso é diferente das bibliotecas que emulam o WhatsApp Web (Baileys, WPPConnect), que mantêm uma sessão aberta por QR Code. A comparação completa está em API oficial x API não oficial.
O fim da On-Premises API
Até 2025, havia duas formas oficiais de rodar a plataforma: a Cloud API, hospedada pela Meta, e a On-Premises API, em que a empresa (ou o provedor) hospedava um cliente em contêineres próprios. A Meta encerrou a segunda em etapas, conforme a página de descontinuação da On-Premises API:
| Data | O que mudou |
|---|---|
| 9 de janeiro de 2024 | Novos recursos passaram a sair só na Cloud API; a On-Premises recebia apenas correções |
| 1º de julho de 2024 | Números comerciais só podem ser registrados para uso na Cloud API |
| 23 de outubro de 2025 | A última versão do cliente On-Premises expirou; mensagens de números ainda registrados nela deixaram de ser entregues |
Na prática, se você ler hoje “API oficial do WhatsApp”, “WhatsApp Business API” ou “Cloud API”, todos apontam para o mesmo produto. Tutoriais antigos que falam em instalar contêiner Docker do WhatsApp estão desatualizados.
Componentes da plataforma
A documentação da Meta organiza a plataforma em algumas peças. Vale entender cada uma, porque elas aparecem em endpoints e permissões diferentes:
| Componente | Para que serve |
|---|---|
| Cloud API | Enviar e receber mensagens, fazer chamadas e gerenciar grupos |
| Business Management API | Gerenciar contas de mensagens (WABA), números, templates, cobrança e métricas |
| Marketing Messages API | Envio de mensagens de marketing otimizadas, com métricas de entrega e conversão |
| Webhooks | Avisar seu servidor sobre mensagens recebidas e mudanças de status, em JSON |
| Meta Business Agent | Configurar agentes de IA da própria Meta que respondem conversas |
E alguns objetos que você vai usar o tempo todo:
- Portfólio empresarial (antigo Business Manager): a conta da empresa na Meta.
- Conta de mensagens (WABA,
waba_id): agrupa números e templates. - Número de telefone comercial (
phone_number_id): é ele que vai na URL de envio. - App da Meta: o app criado no painel de desenvolvedores, ligado ao portfólio, que recebe permissões e webhooks.
- Token de acesso: para produção, um token de usuário do sistema com as permissões
whatsapp_business_messaging,whatsapp_business_managementebusiness_management. Detalhes em token permanente com usuário do sistema.
Como funciona o envio de uma mensagem
O envio é um POST para /{phone_number_id}/messages. O exemplo abaixo manda um template para um número brasileiro direto na Graph API (troque a versão pela atual indicada no changelog da Meta):
curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages" \
-H "Authorization: Bearer TOKEN_DO_USUARIO_DO_SISTEMA" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999999999",
"type": "template",
"template": {
"name": "confirmacao_pedido",
"language": { "code": "pt_BR" },
"components": [
{ "type": "body", "parameters": [ { "type": "text", "text": "Maria" } ] }
]
}
}'A resposta traz o wa_id do destinatário e o identificador da mensagem (wamid):
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }],
"messages": [{ "id": "wamid.HBgLNTUxMTk5OTk5OTk5..." }]
}Essa resposta só confirma que a Meta aceitou a mensagem. Entrega, leitura e falha chegam depois pelo webhook, como explicamos em status de mensagem via webhook. Mais exemplos de envio em cURL, Node.js e Python estão em como enviar mensagem pela API do WhatsApp.
Duas regras que mudam o código
- Janela de atendimento de 24 horas. Quando o cliente escreve, você pode responder com mensagens livres por 24 horas. Fora disso, só template aprovado. Veja janela de 24 horas do WhatsApp.
- Templates com categoria. Marketing, utilidade ou autenticação. A categoria define o preço e é revisada pela Meta. Veja templates da API do WhatsApp.
Como funciona o recebimento: webhooks
Quando um cliente responde, a Meta faz um POST no seu endpoint com o objeto whatsapp_business_account. As mensagens e os status ficam dentro de entry[].changes[].value:
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WABA_ID",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "phone_number_id": "PHONE_NUMBER_ID" },
"contacts": [{ "wa_id": "5511999999999", "profile": { "name": "Maria" } }],
"messages": [{
"from": "5511999999999",
"id": "wamid.HBgL...",
"timestamp": "1761400000",
"type": "text",
"text": { "body": "Quero acompanhar meu pedido" }
}]
}
}]
}]
}Seu servidor precisa responder rápido com 200, validar a assinatura do payload e processar o evento em fila. O passo a passo está em Webhooks da API do WhatsApp.
Limites da Cloud API
| Limite | Valor | Fonte |
|---|---|---|
| Throughput por número | Até 80 mensagens por segundo por padrão | Throughput |
| Throughput ampliado | 1.000 mps, automático para números elegíveis (limite ilimitado, 100 mil usuários únicos em 24 h, qualidade amarela ou melhor) | Throughput |
| Números em coexistência | 20 mps fixos | Throughput |
| Limite de mensagens | 250 destinatários únicos em 24 h fora da janela para portfólios novos; depois 2.000, 10.000, 100.000 e ilimitado | Limites de mensagens |
| Números por portfólio | 2 no início; 20 após verificação da empresa ou ao chegar ao limite de 2.000 | Números de telefone |
Quem passa do throughput recebe o erro 130429 até a taxa voltar ao permitido. O limite de mensagens é calculado por portfólio e compartilhado entre todos os números dele. Mais detalhes em limite de mensagens da API do WhatsApp.
Quanto custa a WhatsApp Cloud API
A Cloud API não tem mensalidade da Meta nem cobrança por hospedagem. O custo é por mensagem entregue, segundo a página de preços:
- só mensagens da empresa para o usuário são cobradas; o que o cliente manda não custa nada;
- o preço depende da categoria (marketing, utilidade, autenticação, serviço) e do país do destinatário;
- cada número tem 1.000 mensagens de serviço gratuitas por mês;
- mensagens dentro da janela de ponto de entrada gratuito, aberta por anúncios de clique para o WhatsApp, não são cobradas (exceto as do Meta Business Agent);
- a Meta só muda preços no primeiro dia de cada trimestre.
Para destinatários no Brasil, a tabela em reais em vigor desde 1º de outubro de 2026 é:
| Categoria | Preço por mensagem entregue |
|---|---|
| Marketing | R$ 0,3217 |
| Utilidade | R$ 0,0350 |
| Autenticação | R$ 0,0350 |
| Serviço (após 1.000 por número no mês) | R$ 0,0350 |
Desde 1º de outubro de 2026, utilidade dentro da janela de atendimento também é cobrada, e contas sem forma de pagamento deixam de ter mensagens de serviço entregues depois da franquia. Faixas de volume e exemplos de cálculo estão em quanto custa a API do WhatsApp no Brasil. Se você quer saber o que dá para fazer sem pagar nada, veja existe API do WhatsApp grátis?.
A esse valor soma-se o custo de quem opera a integração: o seu time, se você integrar direto, ou o provedor que você escolher.
Integrar direto ou usar um provedor
Integrar direto com a Cloud API é possível: criar o app, gerar o token de usuário do sistema, configurar o webhook, cadastrar forma de pagamento na conta de mensagens e cuidar de tudo isso em produção. Um provedor tira parte desse trabalho, e os critérios para escolher um estão em como escolher um provedor de API do WhatsApp.
WhatsApp Cloud API com a Vectalk
A Vectalk é um proxy da WhatsApp Cloud API: sua aplicação chama a Vectalk, que repassa a chamada para a Meta. Os payloads são os mesmos da Meta; mudam a URL base e o token.
| Cloud API direta | Vectalk | |
|---|---|---|
| URL base | https://graph.facebook.com/vXX.X | https://apis.vectalk.com.br/api |
| Token | Usuário do sistema da Meta | Token gerado no painel da Vectalk |
| Webhooks | Formato da Meta, um endpoint por app | Formato da Meta, várias URLs por instância |
| Pagamento da Meta | Forma de pagamento na conta de mensagens | Você paga a Vectalk, e a Vectalk paga a Meta |
A Vectalk também oferece coexistência: o número continua no app WhatsApp Business e passa a funcionar na API. Para começar, crie a conta em apps.vectalk.com.br/register e siga o guia rápido.
Perguntas frequentes
Cloud API e WhatsApp Business API são a mesma coisa?
Hoje, sim. “WhatsApp Business API” era o nome usado quando havia duas versões. Com o fim da On-Premises API em 23 de outubro de 2025, a Cloud API é a única forma oficial de usar a plataforma.
Preciso de servidor para usar a Cloud API?
Não para hospedar o WhatsApp, que roda na Meta. Você só precisa de um endpoint HTTPS público para receber webhooks, que pode ser uma função serverless ou um servidor comum.
A WhatsApp Cloud API é gratuita?
Usar a API não tem mensalidade da Meta, mas as mensagens são cobradas por entrega, conforme categoria e país. Há franquia de 1.000 mensagens de serviço por número por mês e janelas sem cobrança para conversas vindas de anúncios.
Qual versão da Graph API devo usar?
A versão mais recente listada no changelog da Meta. Cada versão tem prazo de descontinuação, então trate a versão como configuração e não deixe fixa no código.
Posso usar o número que já está no meu celular?
Se ele está no app WhatsApp Business, sim, pela coexistência. Se está no WhatsApp comum, é preciso excluir a conta do app antes de registrar o número. Veja coexistência no WhatsApp.
Fontes oficiais consultadas em 25/10/2026: Visão geral da Cloud API, Descontinuação da On-Premises API, Primeiros passos, Throughput, Limites de mensagens, Números de telefone, Preços, Documentação da Vectalk.