Colocar a API do WhatsApp em produção: checklist completo

9 de outubro de 2026·7 min de leitura

Resposta rápida

Sair do teste exige seis frentes prontas: token permanente de usuário do sistema, webhook validado e monitorado, templates aprovados nas categorias certas, empresa verificada, controle da janela de 24 horas por contato e alertas para os erros que param a operação em silêncio — 131042 (cobrança) e 132015 (template pausado).

O ambiente de teste da Cloud API é generoso: número pronto, token na tela, alguns destinatários cadastrados e mensagem saindo em dez minutos. É justamente por isso que a passagem para produção surpreende — metade do que funcionava era muleta do sandbox.

Este é o checklist entre o teste e o primeiro cliente real, agrupado por frente. Nenhum item aqui é opcional em operação que atende gente de verdade.

1. Credenciais

O token do painel de desenvolvedores vale 24 horas. Toda integração que “parou sozinha sem ninguém mexer” é este item.

Credenciais

Token de usuário do sistema criado, não o temporário do painel.
Permissões whatsapp_business_messaging e whatsapp_business_management concedidas.
Token guardado em variável de ambiente ou cofre — nunca no código, nunca no repositório.
phone-number-id anotado e conferido: é o ID do número, não o da conta comercial.
Segredo do app guardado, para validar a assinatura do webhook.
Alguém além de uma pessoa tem acesso administrativo ao portfólio comercial.

2. Webhook

Enviar é uma requisição. Receber é infraestrutura — e é onde produção difere de teste de verdade.

Webhook

URL pública com HTTPS e certificado válido.
Verificação (GET) devolvendo o hub.challenge como texto puro.
Recebimento (POST) respondendo 200 antes de processar.
Deduplicação pelo id da mensagem — a Meta reenvia o que demora a confirmar.
Assinatura X-Hub-Signature-256 validada sobre o corpo cru.
Ordenação por timestamp, não por ordem de chegada.
Monitoramento com alerta: webhook fora do ar derruba o atendimento inteiro.

O detalhe que quebra a validação de assinatura: se o framework já converteu o JSON em objeto e você reserializa para calcular o HMAC, o resultado nunca bate. Guarde o corpo cru antes do parser. O detalhamento está em webhooks do WhatsApp.

3. Templates

Templates

Todos os templates necessários criados e aprovados antes da data de uso.
Categoria correta: utilidade e marketing em templates separados, nunca no mesmo.
Idioma conferido — pt_BR e pt são templates diferentes.
Variáveis sanitizadas: sem quebra de linha, sem tabulação, com tamanho truncado.
Valor padrão para variável que pode vir vazia — string vazia continua contando como parâmetro.
Botão de saída nos templates de marketing.
Nomes versionados (pedido_confirmado_v2), com o motivo de cada versão registrado.

Criar template no dia da campanha é o erro de planejamento mais caro. Recusa mais correção mais nova análise consome um dia inteiro — e a campanha já estava marcada.

4. Conta e limites

Item	Por que trava produção
Empresa verificada	Sem isso a conta fica presa na faixa inicial de envio
Nome de exibição aprovado	É o que o cliente vê sem ter você salvo
Método de pagamento válido	Sem ele o envio para com erro 131042, em silêncio
Faixa de envio conhecida	Planejar campanha sem saber o teto é planejar a falha
Qualidade do número monitorada	Queda congela a subida e pode derrubar a faixa

As duas primeiras linhas dependem de análise da Meta e levam dias. Comece por elas — os detalhes estão em Meta Business.

5. A janela de 24 horas

É a regra que mais gera chamado depois do go-live, e a correção é de estrutura de dados, não de código de envio.

Controle da janela

Horário da última mensagem recebida guardado por contato.
Antes de enviar, o sistema compara: menos de 24h manda texto livre; mais, manda template.
Toque em botão interativo também atualiza esse horário — conta como mensagem do cliente.
Erro 131047 tratado como regra de negócio, não como falha técnica.

1
Vou enviar
Consulta o horário da última mensagem dele
2
Menos de 24h?
Texto livre, sem custo
3
Mais de 24h?
Template aprovado, cobrado
4
Ele respondeu
Atualiza o horário e reabre a janela

Quatro passos que eliminam o erro mais comum da API. O mecanismo está em [janela de 24 horas](/blog/janela-24-horas-whatsapp).

6. Monitoramento

Dois erros param a operação sem gerar reclamação imediata, porque nada quebra visivelmente — as mensagens simplesmente deixam de sair.

Erro	O que aconteceu	Como monitorar
131042	Cobrança recusada na conta comercial	Alerta imediato, não log
132015	Template pausado por baixa qualidade	Alerta imediato — indica bloqueios em massa
190	Token expirado ou revogado	Alerta imediato
130429	Velocidade excedida	Métrica, com repetição automática
Webhook sem eventos	Endpoint caiu, ou a assinatura foi desativada	Alerta por ausência de tráfego

As três primeiras linhas merecem acordar alguém. As demais são painel.

O primeiro dia em produção

1Comece pelo atendimento, não pela campanha. Deixe o número receber e responder por alguns dias antes de qualquer envio ativo.
2Envie o primeiro template para você mesmo e para dois colegas, em aparelhos diferentes, incluindo um iPhone.
3Faça o primeiro disparo real pequeno — algumas dezenas de contatos engajados — e acompanhe a qualidade nas 24 horas seguintes.
4Confira o webhook recebendo status de entregue e lido, não só mensagens novas.
5Teste o caminho de falha: desligue o endpoint por um minuto e confirme que o alerta dispara.
6Só então aumente o volume, e de forma gradual.

As três frentes que ninguém lembra

Fora da lista técnica, três coisas costumam ser descobertas depois do primeiro envio real.

Registro de consentimento. Sob a LGPD, você precisa conseguir demonstrar que a pessoa aceitou receber mensagens: data, origem e o texto exato que ela aceitou. Isso é estrutura de dados, e é mais fácil criar antes do primeiro contato entrar na base do que reconstruir depois.
Caminho de descadastro. Um botão de saída em todo template de marketing troca um bloqueio — que pesa na qualidade do número — por um opt-out, que não pesa. Precisa existir no template e ser tratado no seu sistema, senão a pessoa pede para sair e continua recebendo.
A equipe. Envio ativo gera resposta, e resposta chega toda junta. Disparo feito às 9h com ninguém escalado para atender às 9h05 produz o pior resultado possível: você pagou pela mensagem e o cliente ficou sem resposta.

Perguntas frequentes

Quanto tempo leva para colocar a API do WhatsApp em produção?

O ambiente de teste é imediato e o envio funciona em minutos. O que define o prazo é a verificação da empresa, que depende de documentos e leva de dias a semanas, e a aprovação dos templates, que costuma sair em horas.

Posso usar o token do painel em produção?

Não. Ele expira em 24 horas. Produção exige um token de usuário do sistema, criado nas configurações do portfólio comercial, que não expira e pode ser revogado se vazar.

Preciso de webhook mesmo se só envio mensagens?

Para enviar, não. Mas sem webhook você não recebe resposta nenhuma, não sabe se a mensagem foi entregue e não consegue controlar a janela de 24 horas — o que torna o canal de mão única.

Qual o erro mais comum no primeiro dia?

O 131047, janela fechada, seguido do 33, que é usar o ID da conta comercial no lugar do ID do número. Os dois são de entendimento, não de código.

Como testar sem incomodar clientes reais?

A Meta oferece um número de teste com alguns destinatários cadastrados, sem custo. É onde se reproduzem erros de template e de credencial antes de qualquer envio real.

Preciso de ambiente separado para testar?

Sim, e é o item que mais evita acidente. Sem um ambiente à parte, todo template novo e todo fluxo recém-escrito são testados no número que atende clientes reais — que é onde nascem os disparos acidentais.

O que monitorar depois do go-live?

Três alertas que acordam alguém: 131042 (cobrança recusada), 132015 (template pausado por qualidade) e 190 (token inválido). Mais um alerta por ausência de eventos no webhook, que é a falha silenciosa.

Termos deste artigo

Cloud API: Versão da API oficial do WhatsApp hospedada pela própria Meta, sem custo de hospedagem. É o caminho atual para integrar o WhatsApp a um sistema; a alternativa antiga, On-Premises, foi descontinuada.
Webhook: URL pública onde a Meta entrega os eventos do seu número: mensagem recebida, confirmação de entrega e de leitura. Não existe consulta sob demanda na API do WhatsApp — receber mensagem exige um servidor sempre no ar.
Template de mensagem(HSM): Mensagem escrita antes, submetida à Meta e aprovada, com espaços para variáveis. É a única forma de falar com quem não escreveu para a empresa nas últimas 24 horas. Classificado pela Meta em marketing, utilidade, autenticação ou serviço — e o preço varia conforme a categoria.
Janela de 24 horas: Período em que uma empresa pode responder livremente a um cliente pela API oficial do WhatsApp. Abre a cada mensagem que o cliente envia e dura 24 horas a partir dela. Dentro da janela, a conversa não é cobrada; fora dela, só sai template aprovado, que é cobrado.
Conta comercial do WhatsApp(WABA): WhatsApp Business Account — o objeto dentro do Meta Business que agrupa os números de telefone, os templates e os limites de envio de uma empresa na API oficial. Deve ficar no Meta Business da própria empresa, não no do fornecedor.
Qualidade do número: Nota que a Meta atribui a um número na API oficial, calculada principalmente a partir de bloqueios e denúncias de quem recebe. Qualidade baixa derruba o limite de envio e pode restringir o número.

Ver o glossário completo do WhatsApp

Resumo

Token de usuário do sistema, nunca o temporário de 24 horas.
Webhook com 200 antes de processar, deduplicação por id e assinatura sobre o corpo cru.
Templates aprovados antes da data de uso, com variáveis sanitizadas.
Empresa verificada e método de pagamento válido — os dois travam produção em silêncio.
Guarde o horário da última mensagem de cada contato: é o que elimina o 131047.
Alerta para 131042, 132015, 190 e para ausência de eventos no webhook.

Referências oficiais

Cloud API — primeiros passos — consultado em 9 de outubro de 2026
Cloud API — webhooks — consultado em 9 de outubro de 2026
Cloud API — códigos de erro — consultado em 9 de outubro de 2026