WhatsApp Cloud API: o que é e como integrar (número, token, webhook e primeiro envio)

O que é a WhatsApp Cloud API

A Cloud API é a parte da WhatsApp Business Platform que envia e recebe mensagens a partir de um sistema, e não de um celular. Ela usa a Graph API da Meta para enviar e webhooks para avisar o que chega e o que aconteceu com cada mensagem. Quem fala em “API do WhatsApp” ou em API oficial do WhatsApp fala dela.

Existia uma versão instalada nos servidores da própria empresa, a On-Premises API, mas a Meta levou a plataforma inteira para a nuvem. A página de descontinuação diz que, desde 1º de julho de 2024, número novo só se registra na Cloud API, e que a última versão do On-Premises, a v2.63, expirou em 23 de outubro de 2025.

A diferença para o app WhatsApp Business é que a API não tem tela: é um conjunto de endpoints, e a conversa aparece onde o seu sistema mostrar. Em troca, abre o que o app não tem: atendentes sem limite de aparelhos, automação, integração com loja e CRM e mensagens interativas, como botões, listas e os formulários do WhatsApp Flows.

O que precisa existir antes do código

O guia de início da Meta pede uma conta de desenvolvedor, um app no Meta for Developers com o caso de uso “Connect with customers through WhatsApp”, um portfólio empresarial e uma conta do WhatsApp Business. O painel cria sozinho uma conta e um número de teste, com limites folgados e envio de template sem forma de pagamento cadastrada.

Em 2026 a conta mudou. Desde 23 de setembro, o novo modelo a divide em duas: a conta do WhatsApp, com o número e o nome de exibição, e a conta de mensagens, com templates, cobrança e webhooks. O ID antigo vira o da conta de mensagens, e nada quebra agora. No primeiro semestre de 2028, os caminhos da API trocam o ID do número pelo da conta do WhatsApp; guarde os dois desde já.

O número precisa ser seu, com código de país e de área, e receber código por SMS ou ligação; código curto não vale. Se ele já está no WhatsApp, a conta precisa ser apagada antes. A exceção é a coexistência com o app WhatsApp Business, que mantém o número no celular e na API, mas entra pelo cadastro de um parceiro ou provedor de tecnologia da Meta, e não pela integração direta.

A verificação da empresa não é obrigatória para começar, mas muda os tetos: com o portfólio verificado, o limite de números passa de 2 para 20, o de mensagens sai de 250 para 2.000 pessoas por dia, e o de templates, de 250 para até 6.000 quando um número já tem o nome de exibição aprovado.

Token permanente e registro do número

O botão “Generate access token” do painel gera um token de usuário, que a documentação diz expirar a cada poucas horas: serve para o primeiro teste. Em produção, o token é de um usuário do sistema, criado nas configurações do portfólio com acesso ao app e às contas do WhatsApp, de longa duração e com três permissões: business_management, whatsapp_business_management e whatsapp_business_messaging.

whatsapp_business_messaging cobre o envio e o webhook de mensagens; whatsapp_business_management, números, templates e os outros campos. Quem integra os próprios dados concede as duas ao gerar o token; a análise da Meta para acesso avançado é exigida de parceiros. O token mora num cofre de segredos do servidor, nunca no front-end ou no repositório, e vencido aparece como erro 190.

Adicionar e verificar o número no WhatsApp Manager não basta: o registro na Cloud API só se faz pela API, com POST /<PHONE_NUMBER_ID>/register, messaging_product: "whatsapp" e um pin de seis dígitos, o da verificação em duas etapas (o atual, se existe, ou um novo). São 10 pedidos por número a cada 72 horas; passou disso, erro 133016 e 72 horas de bloqueio.

O parâmetro opcional data_localization_region liga o armazenamento local, e a lista inclui o Brasil (BR): depois de processado, o conteúdo das mensagens fica só em data centers do país escolhido. Para mudar, só cancelando o registro e registrando de novo. E cada mudança aprovada do nome de exibição exige novo registro em até 14 dias.

O primeiro envio

A chamada é POST https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>/messages, com o token em Authorization: Bearer. O corpo leva messaging_product: "whatsapp", recipient_type: "individual", o número em to, o type e um objeto com o nome do tipo, como text. A v26.0, de 29 de julho de 2026, é a versão mais recente da Graph API.

Fixe a versão na configuração e mude de propósito. O guia de início da Meta ainda mostra a v23.0, que vale até 8 de outubro de 2027; cada versão tem data de validade na tabela da Graph API, e quem copia o exemplo fica numa versão com prazo sem perceber.

Texto livre só sai dentro da janela de atendimento, que a documentação diz abrir quando o cliente manda mensagem ou liga, durar 24 horas e reiniciar a cada nova mensagem dele. Fora dela, só template aprovado: type: "template", com name, language.code e os components das variáveis. Os detalhes estão no post sobre a janela de 24 horas do WhatsApp.

A resposta traz contacts, com o número em input e o wa_id, que pode ser diferente, e messages[0].id, o wamid. A Meta avisa que ela só confirma que a API aceitou o pedido, não a entrega, e que a ordem de entrega pode não seguir a das chamadas. Guarde o wamid antes de tudo: ele liga o envio aos status do webhook.

Webhook: verificação, assinatura e inscrição

Ao cadastrar a URL do webhook no painel, a Meta manda um GET com hub.mode=subscribe, hub.verify_token e hub.challenge. Se o verify_token bate com a string que você escolheu, responda 200 com o valor de hub.challenge no corpo; qualquer outra resposta deixa o endpoint sem verificação, e nenhum webhook chega. O certificado TLS precisa ser válido: autoassinado não é aceito.

Cada POST traz o cabeçalho X-Hub-Signature-256, no formato sha256=<hash>: um HMAC-SHA256 do corpo com o app secret como chave. Calcule sobre os bytes crus da requisição, antes do parse do JSON, compare em tempo constante e descarte o que não bate. A Meta também aceita mTLS e o recomenda no lugar de liberar IPs, porque os endereços dela mudam.

No painel, assine o campo messages: ele traz as mensagens dos clientes e os status das que você enviou. Inscreva o app em cada conta com POST /<WABA_ID>/subscribed_apps, uma por uma, como pede a documentação. E publique o app em modo Live: a Meta avisa que alguns webhooks não são enviados com o app em desenvolvimento.

Webhook em produção: 200 rápido, fila e idempotência

Se o endpoint responde algo diferente de 200, ou a entrega falha, a Meta tenta de novo, cada vez mais espaçado, por até 7 dias, e a documentação avisa que isso gera duplicatas que o servidor deve descartar. Um payload tem até 3 MB e pode juntar até 1.000 atualizações. Não existe API para buscar webhooks antigos: o que não foi gravado se perde.

O desenho certo: o handler confere a assinatura, grava o payload cru numa fila ou tabela durável e responde 200. Atualizar a conversa, baixar mídia ou chamar o CRM e o agente de IA fica para um worker. Handler que demora a responder arrisca reentrega e a mesma mensagem processada duas vezes.

Idempotência pelo id: mensagem recebida tem chave única no messages[].id, e status, no wamid mais o status. E não conte com a ordem: quando o cliente lê na hora, o delivered nem é enviado, e uma reentrega pode trazer um status antigo depois de um novo. Trate o status como escada, sent, delivered, read, que nunca desce; o failed chega com errors.

Desde abril de 2026 os webhooks trazem o BSUID, um ID do cliente por portfólio, em campos como contacts[].user_id. Quando o cliente usa nome de usuário, o telefone pode não vir, e a Meta recomenda não contar com wa_id e from. Desde julho dá para enviar pelo BSUID, no campo recipient. Modele o contato com as duas chaves.

Mídia, limites e os erros mais comuns

Para enviar mídia, suba o arquivo com POST /<PHONE_NUMBER_ID>/media e use o id que volta, que a Meta recomenda no lugar de um link; ele fica guardado por 30 dias. Imagem é JPEG ou PNG de 8 bits, em RGB ou RGBA, até 5 MB: o JPEG em CMYK de gráfica não passa.

Na chegada, o webhook traz o id da mídia, não o arquivo. GET /<MEDIA_ID> devolve uma URL que expira em 5 minutos, o download exige o token, e o id recebido só vale por 7 dias. Copie o arquivo para o seu armazenamento assim que a mensagem chegar.

Há dois tetos. A vazão: cada número envia até 80 mensagens por segundo e sobe sozinho para 1.000 com o portfólio ilimitado, 100 mil pessoas fora da janela em 24 horas e qualidade amarela ou melhor; em coexistência, fica em 20. E o limite de mensagens, que conta pessoas fora da janela em 24 horas no portfólio inteiro e sobe de 2.000 a 10.000, 100.000 e ilimitado com qualidade alta e metade do teto usada em 7 dias.

Os erros comuns cabem em três grupos. Os que pedem espera e retentativa com intervalo crescente: 130429, de vazão, e 131056, mensagens demais para a mesma pessoa. Os que pedem outra mensagem: 131047, janela fechada, e 132001, template inexistente no idioma. E os que pedem gente: 190, token vencido; 133010, número não registrado; 131042, pagamento; e 131048, número restrito por spam. O post sobre os erros da Cloud API detalha os mais traiçoeiros.

Integrar direto ou por um parceiro da Meta

Integrar direto dá controle total e deixa com você o que a API não faz: a fila que respeita a vazão, a retentativa, a guarda dos webhooks, a cópia da mídia, o cálculo da janela por contato e as trocas de versão. E as mudanças da Meta: ela anunciou que, depois de 13 de outubro de 2027, marketing pela Cloud API dá erro e passa para a Marketing Messages API.

A API também não tem inbox: distribuir conversas, mostrar o histórico, avisar quem atende e dar um painel ao gestor é software a construir e manter. A conta da Meta é a mesma nos dois caminhos: por mensagem entregue, por categoria e país, incluindo, desde 1º de outubro de 2026, as de serviço acima de 1.000 por número no mês.

A plataforma de um Meta Business Partner entrega essas peças prontas: conecta o número pelo cadastro da Meta, oferece a coexistência e dá o inbox à equipe. Você integra com a API e o webhook dela, como nesta documentação da API de mensagens para WhatsApp, e o número segue na sua conta do WhatsApp. Se o WhatsApp é o centro do produto e há engenharia para mantê-lo, vá direto; se é um canal da operação, plataforma.