A WhatsApp Cloud API faz parte da WhatsApp Business Platform e é a forma atual de acessar a API oficial do WhatsApp. Trata-se da versão da API hospedada pela própria Meta: a empresa não instala nem mantém a API em servidor próprio, apenas integra seus sistemas por HTTPS e recebe os eventos por webhook.
A seguir estão as diferenças para a On-Premises e o app, as formas de acesso, o passo a passo até a produção, tokens, webhooks, mídia, custos e erros comuns.
Principais Conclusões
- Teste com o template
hello_worldno painel do app antes de escrever qualquer integração. - Em produção, use token de usuário do sistema, registre o número com PIN e sirva o webhook com certificado TLS válido.
- Baixe e guarde a mídia recebida logo que o evento chega, porque a URL expira em minutos.
O Que É a WhatsApp Cloud API
Muita gente pesquisa o termo achando que se trata de um aplicativo. A Cloud API não tem tela própria: é uma interface de programação que conecta os sistemas da empresa ao WhatsApp.
Definição e Origem da Versão em Nuvem
A Cloud API permite enviar mensagens e fazer chamadas pelo WhatsApp de forma programática. Em vez de alguém digitar no celular, um sistema envia textos, mídias e mensagens interativas a partir de regras, integrações ou agentes de IA.
A versão em nuvem foi aberta a qualquer empresa em 2022, conforme o anúncio da Meta no evento Conversations. A proposta era oferecer hospedagem gratuita nos servidores da própria Meta e acesso em minutos, sem a infraestrutura exigida pelo modelo anterior.
É comum confundir a API com o WhatsApp Business, o aplicativo gratuito para pequenos negócios. O app é operado à mão, no celular, enquanto a Cloud API é operada por software e acompanha o crescimento de equipes e automações.
Componentes da WhatsApp Business Platform
A Cloud API cuida do envio e do recebimento de mensagens e chamadas. A Business Management API gerencia números, templates, métricas e custos, os webhooks entregam os eventos e a Marketing Messages API atende campanhas com rastreio de conversões.
Na prática, todo projeto usa pelo menos a Cloud API e os webhooks. Para o panorama de regras, preços e requisitos, o guia da API oficial reúne cada tema, enquanto este texto foca na configuração técnica.
Chamadas HTTPS, Fluxo e Status
Segundo a documentação da Meta, toda ação é uma requisição HTTPS, com criptografia TLS, a um endpoint da Graph API. O endereço inclui a versão da Graph API (no formato /vXX.0/) e o identificador do número que envia.
A versão atual aparece no changelog da Meta. Fixar a versão no código evita surpresas: a integração segue estável até a equipe testar a nova versão em homologação e migrar, em vez de quebrar quando uma versão antiga deixa de ser aceita.
Esse modelo segue o padrão de integração adotado em projetos de inteligência artificial nas empresas. Para enviar, o ERP, o CRM ou o agente de IA fazem um POST com o destinatário e o conteúdo, sem depender de alguém com o celular na mão.
Mensagens recebidas e status das enviadas, como entregue e lida, voltam por webhook, e é esse retorno que permite ao atendimento via WhatsApp saber se o cliente leu o aviso. Fora da janela de atendimento de 24 horas, só é permitido enviar templates aprovados.
Cloud API x On-Premises x App e Formas de Acesso
A escolha envolve duas decisões: qual modelo usar e quem vai operar a integração. Um dos três modelos saiu de cena, os outros dois atendem necessidades diferentes, e o acesso pode ser direto ou por parceiro.
Fim da On-Premises e o Padrão em Nuvem
Pelo cronograma de encerramento publicado pela Meta, recursos novos passaram a sair só na nuvem em janeiro de 2024. A partir de julho de 2024, números novos só podiam ser registrados na Cloud API.
Em 23 de outubro de 2025, a última versão On-Premises expirou, e as mensagens de números ainda registrados nela deixaram de ser entregues. Desde então, a Cloud API é a única versão da API oficial em operação.
Por isso, tutoriais que mandam instalar servidor próprio estão desatualizados. Projetos de automação de atendimento iniciados agora já nascem na nuvem, com a infraestrutura de mensageria a cargo da Meta.
Quando o App Basta e Quando Migrar
O app WhatsApp Business funciona bem para quem atende sozinho ou com poucas pessoas. Quando a operação precisa de vários atendentes, integração com sistemas ou automação, a API passa a fazer mais sentido. A tabela resume as diferenças, com base no comparativo oficial do WhatsApp Business.
| Critério | App WhatsApp Business | WhatsApp Cloud API |
|---|---|---|
| Números por conta | Um número | Vários números e nomes de exibição |
| Usuários | Uso individual ou equipe pequena | Milhares de atendentes e bots |
| Integração com CRM | Sem integração por API | Por API e webhooks |
| Automação | Recursos do próprio app | Agentes de IA e fluxos integrados |
| Custo | App gratuito | Hospedagem gratuita; cobrança por template entregue (ver tabela da Meta) |
Migrar não obriga a empresa a abandonar o app. Com a coexistência, ativada por meio de um parceiro, o mesmo número funciona no app WhatsApp Business e na Cloud API ao mesmo tempo, e as mensagens enviadas pelo app continuam gratuitas.
Acesso Direto pela Meta ou por Parceiro
A Cloud API é a mesma nos dois caminhos; muda quem constrói, hospeda e mantém a integração. O guia de primeiros passos da Meta descreve o acesso direto: um app Meta com o caso de uso WhatsApp, uma conta WhatsApp Business, chamada de WABA, e um número.
A partir daí, quase tudo é código, com equipe de desenvolvimento e servidor com HTTPS para os webhooks. Quem já passou pela criação de chatbots reconhece o trabalho, agora somado à gestão de tokens, webhooks e versões da Graph API.
No acesso por parceiro, o caminho é o cadastro incorporado, ou Embedded Signup: o fluxo abre no site do parceiro, cria os ativos do WhatsApp da empresa e autoriza o app do parceiro a operar a conta. Os tipos de parceiros variam na cobrança e no suporte, então vale confirmar que a plataforma usa a API oficial e como cobra.
A ConverZap segue esse modelo de plataforma pronta, no grupo das ferramentas de IA para WhatsApp, conectada à API oficial com coexistência. A conexão com a Meta fica a cargo da plataforma, que reúne disparo com templates e descadastro, repescagem, integrações com CRM e banco de dados e dashboards, e a equipe da empresa trabalha nos fluxos de conversa.
Como Começar na WhatsApp Cloud API: Passo a Passo
O caminho tem duas fases: ver a primeira mensagem chegar ao celular e, depois, dar à integração credenciais definitivas e um número real, pronto para conversar com clientes.
Pré-Requisitos de Conta, Portfólio e Número
Para o teste, a Meta pede conta no Facebook ou conta gerenciada da Meta, cadastro de desenvolvedor, um celular com WhatsApp e um app Meta com o caso de uso WhatsApp, onde ficam painel, tokens e webhook.
Para produção, o Portfólio Empresarial, antigo Business Manager, é obrigatório e reúne as contas WhatsApp Business. A verificação da empresa libera mais vazão e abre o caminho para o status de conta comercial oficial.
Pelos requisitos de número da Meta, a linha precisa ser da empresa, ter código do país e DDD e receber SMS ou ligação. Códigos curtos não são aceitos.
Um número em uso no WhatsApp precisa ser apagado antes, exceto na coexistência. Já um número banido exige recurso do bloqueio antes de ir para a API.
Ambiente de Teste e Template hello_world
A Meta cria um ambiente de teste no painel do app, o que permite enviar a primeira mensagem sem configurar servidor próprio nem webhook. O roteiro básico segue esta ordem:
- Criar o app Meta e adicionar o caso de uso WhatsApp.
- Clicar em “Generate access token” para gerar um token temporário.
- Cadastrar o número do celular que vai receber o teste.
- Enviar o template
hello_worlde conferir a chegada no aparelho.
Segundo a Meta, o token temporário expira rápido e não serve para desenvolvimento. Para estudar um fluxo completo, há o app de exemplo Jasper’s Market, com o código da demonstração.
Com a primeira mensagem entregue, falta definir o que vai responder ao cliente. Muitas equipes começam com um chat bot para WhatsApp de dúvidas frequentes, e outras já avaliam como integrar IA ao WhatsApp em vez de montar só respostas fixas.
Do Teste à Produção
Para configurar a WhatsApp Cloud API em produção, a sequência indicada pela documentação da Meta troca as credenciais de teste por definitivas e conecta um número da empresa:
- Criar um usuário do sistema no Portfólio Empresarial.
- Gerar um token permanente com a permissão
whatsapp_business_messaging. - Adicionar o número real à conta WhatsApp Business.
- Registrar o número com
POST /PHONE_NUMBER_ID/registere um PIN de 6 dígitos.
O registro do número tem limite: 10 pedidos por número a cada 72 horas, sob pena do erro 133016. O mesmo vale para o desregistro, e um número desregistrado fica inutilizável até ser registrado de novo.
Forma de pagamento e nome de exibição completam a lista, e o nome passa por aprovação da Meta antes de aparecer aos clientes. Com tudo ativo, a empresa pode automatizar o atendimento sobre uma base estável.
Tokens de Acesso, Segurança e LGPD
O token funciona como a chave da conta. Se ele vazar, qualquer pessoa pode enviar mensagens em nome da empresa, e o prejuízo vai da reputação da marca à nota de qualidade do número.
Tipos de Token e Quando Usar Cada Um
A página sobre tokens de acesso da Meta define três tipos. Usar o tipo errado, como um token de usuário em produção, faz a integração parar de enviar quando a credencial expira:
- Token de usuário: serve só para testes e expira em poucas horas.
- Token de usuário do sistema: tem longa duração e é o recomendado para quem integra direto.
- Token de integração empresarial: é gerado por cliente e usado por parceiros.
Sistemas que consomem o token, como ferramentas de automação para suporte, devem ler a credencial de um cofre ou variável de ambiente. A troca do token precisa ser um procedimento documentado, não uma emergência.
Proteção de Credenciais e Dados dos Clientes
O token deve ficar só no servidor, nunca no código do site, em planilhas ou em mensagens entre a equipe. Também vale conceder a menor permissão possível e revogar o acesso sempre que a empresa trocar de fornecedor.
A Política de Mensagens do WhatsApp Business exige opt-in, ou seja, que o cliente tenha fornecido o número e dado permissão, além do respeito ao opt-out. Vale guardar o registro de cada consentimento junto ao cadastro do contato.
A Lei Geral de Proteção de Dados completa o quadro: a empresa deve coletar só os dados necessários ao atendimento, definir por quanto tempo guarda mídias e conversas baixadas da API e oferecer ao cliente um canal para pedir a exclusão.
Agentes de IA com acesso a pedidos, cadastros ou pagamentos exigem cuidado extra. Regras contra prompt hacking impedem que uma mensagem maliciosa convença o agente a revelar dados ou executar ações indevidas.
Webhooks da WhatsApp Cloud API
O webhook é a parte mais técnica da configuração. É por ele que a empresa recebe mensagens, status e alertas, então qualquer falha aqui deixa o atendimento sem visibilidade do que acontece.
Como Configurar o Webhook: Verificação e Certificado
A página sobre como criar o endpoint de webhook exige um certificado TLS válido. Certificado autoassinado não é aceito, e a Meta também suporta mTLS para quem precisa de autenticação mútua entre servidores.
Na verificação, a Meta envia um GET com os parâmetros hub.mode=subscribe, hub.challenge e hub.verify_token. O servidor confere se o token bate com o configurado no painel e responde 200 devolvendo o challenge.
Depois de verificado, o endpoint passa a repassar os eventos para onde eles geram valor. Um destino frequente é a integração com CRM, que registra cada conversa no histórico do cliente.
Assinatura, Reenvio e Campos Principais
Cada POST traz o cabeçalho X-Hub-Signature-256. O servidor deve calcular o HMAC-SHA256 do payload com o app secret, comparar os valores e descartar qualquer requisição cuja assinatura não confira.
Segundo a visão geral dos webhooks, se o endpoint não responder 200, a Meta reenvia o evento com frequência decrescente por até 7 dias. Por isso, deduplicar eventos é obrigatório, usando o ID de cada mensagem ou status.
Cada notificação pode chegar a 3 MB, e o servidor precisa aceitar esse tamanho. Entre os campos de assinatura, três são centrais para o atendimento: messages, com mensagens recebidas e status das enviadas; account_alerts, com avisos de limites e de conta oficial; e message_template_quality_update, sobre a qualidade dos templates.
Os status de entrega e leitura viram informação de gestão quando alimentam as métricas de atendimento, como tempo de resposta e taxa de leitura de avisos enviados pela empresa.
Mensagens, Mídia e Recursos Interativos
Além do texto, a Cloud API oferece formatos que reduzem o esforço do cliente para responder. Junto com eles vêm regras de arquivo que, quando ignoradas, quebram integrações em produção.
Tipos de Mensagem e Flows
As mensagens de serviço formam três grupos: formatos básicos, como texto com prévia de link, imagem, vídeo, áudio e documento; interativos, como botões de resposta, listas, pedido de localização e botões de URL e de chamada; e comércio, com mensagens de catálogo e reações.
Botões e listas funcionam bem em jornadas curtas. Um chatbot para delivery, por exemplo, pode mostrar o cardápio em lista, confirmar o pedido com botões e pedir a localização do cliente para calcular a entrega.
Para jornadas longas, os Flows criam formulários de várias etapas dentro da conversa, úteis para agendamento, feedback e captação de leads. Eles podem consultar um endpoint em tempo real, como uma agenda de horários livres.
Regras de Mídia: Tamanhos e Prazos
A página de regras de mídia define o upload por POST /PHONE_NUMBER_ID/media, e a mídia enviada fica guardada por 30 dias. Os limites de tamanho por tipo são:
- Imagem: até 5 MB.
- Vídeo e áudio: até 16 MB.
- Documento: até 100 MB.
Na mídia recebida, a URL de download expira em 5 minutos. O caminho seguro é baixar o arquivo logo que o evento chega e guardá-lo no próprio sistema, em vez de salvar só o endereço.
Essa regra é essencial para um chatbot para WhatsApp que analisa comprovantes ou fotos de produtos. O ID recebido por webhook também expira em 7 dias, então o arquivo precisa ir para o armazenamento da empresa no mesmo fluxo.
Custos, Limites e Qualidade na Prática
Cobrança, limites de envio e nota de qualidade mudam o planejamento técnico. Valores e categorias ficam na tabela oficial da Meta, citada a seguir.
Como a Cobrança Entra no Projeto
A hospedagem na nuvem não tem custo. Desde 1º de julho de 2025, a Meta cobra por template entregue, nas categorias marketing, utilidade e autenticação.
Mensagens livres, que não são template e só podem ser enviadas dentro da janela de atendimento, são gratuitas até 30/09/2026, assim como os templates de utilidade enviados dentro dela. A partir de 1º de outubro de 2026, as duas passam a ser cobradas, com franquia de 1.000 mensagens de serviço por número a cada mês. Por isso, lembretes e repescagens de follow-up de vendas que saem com a janela fechada exigem template, e vale concentrar a conversa enquanto o cliente está ativo.
No Brasil, desde 11 de março de 2026, a Meta cobra de provedores de IA de uso geral por mensagens fora de template para números +55. Empresas que usam IA no próprio atendimento não entram nessa regra.
Limites de Envio, Vazão e Nota de Qualidade
Os limites de envio sobem em níveis de 250, 2.000, 10.000 e 100.000 destinatários únicos em 24 horas, até chegar ao ilimitado. Desde outubro de 2025, conforme o aviso de mudança nos limites, o limite vale por portfólio, e a queda de qualidade não rebaixa o nível.
A qualidade pesa de outro jeito: pelas regras de pausa de templates, modelos com sinais negativos ficam pausados por 3 horas, depois por 6 horas e, se o problema persistir, são desativados. A visão geral da plataforma fixa a vazão padrão em 80 mensagens por segundo por número.
Há ainda um limite por par, de uma mensagem a cada 6 segundos para o mesmo usuário. Qualidade alta nasce de mensagens relevantes, e estratégias de retenção de clientes bem segmentadas ajudam a mantê-la.
Casos de Uso e Erros Comuns na Implantação
Com a API configurada, o valor aparece nos casos de uso. O caminho até lá pode esbarrar em erros previsíveis, quase todos ligados a tokens, webhooks e registro do número.
Casos de Uso com Agentes de IA e Integrações
O uso mais completo é o de agentes de inteligência artificial que atendem a qualquer hora e executam ações em outros sistemas, como consultar um pedido, emitir uma segunda via ou registrar um agendamento.
Outros usos frequentes são notificações transacionais e lembretes, repescagem de contatos, disparos com templates e botão de descadastro, além de etapas do funil de vendas que dependem de resposta rápida.
Checklist de Erros Antes da Produção
Os pontos das seções anteriores viram uma checagem rápida antes de ligar a operação. Cada item abaixo trava a ativação ou derruba a entrega quando passa despercebido:
- Token temporário em produção: trocar pelo token permanente do usuário do sistema.
- Webhook sem resposta 200: responder rápido e deduplicar os reenvios.
- Certificado autoassinado: usar certificado TLS válido no endpoint.
- Registro repetido do número: planejar a ativação para evitar o erro 133016.
- URL de mídia guardada: salvar o arquivo, não o link que expira em minutos.
- Envio sem opt-in: denúncias derrubam a qualidade e aumentam o risco de bloqueio.
Perguntas Frequentes sobre a WhatsApp Cloud API
Na prática, é a mesma API oficial. O termo Cloud indica a versão hospedada pela Meta, a única em operação desde o fim da On-Premises, em outubro de 2025. Quem conecta um número à API oficial hoje usa a Cloud API.
Qualquer linguagem que faça requisições HTTPS e receba webhooks, porque a API é baseada em HTTP e na Graph API. A escolha depende da equipe e do servidor que vai hospedar o endpoint, que precisa de certificado TLS válido.
Sim, no modo coexistência. O app WhatsApp Business continua no celular e aceita até quatro dispositivos vinculados, como o WhatsApp Web; as exceções são as versões para Windows e WearOS. Na ativação, os aparelhos são desvinculados e precisam ser conectados de novo.
O ambiente de teste fica pronto rapidamente no painel do app. A produção depende de etapas como a verificação do portfólio, a aprovação do nome de exibição e o registro do número, e o prazo varia conforme cada caso.
Sim. A documentação da Meta lista chamadas e grupos entre os recursos da Cloud API, ao lado de texto, mídia e mensagens interativas. Os dois recursos são acionados pela mesma integração por HTTPS usada nas mensagens.
A Conta Comercial Oficial exige portfólio verificado, verificação em duas etapas ativa, nome de exibição aprovado, pelo menos 30 dias na plataforma e respeito às políticas. O pedido é feito no WhatsApp Manager ou pela API.
A nuvem virou o padrão da API oficial, e o projeto se decide em três frentes: validar a ideia no ambiente de teste, trocar as credenciais provisórias por um usuário do sistema com número registrado e preparar webhook e mídia para reenvios e prazos curtos. Com essa base, a automação cresce sem retrabalho.
Para colocar agentes de IA para atender pela API oficial, com coexistência, conheça a plataforma da ConverZap.
