Documentação da API oficial do WhatsApp: por onde começar de verdade

Quando alguém chega até a gente com a documentação da API oficial do WhatsApp aberta em vinte abas e ainda sem saber por onde começar, o problema quase nunca é falta de material. É excesso. A Meta publica referência técnica completa, mas espalhada entre Cloud API, Graph API, webhooks, templates e o Gerenciador de Negócios. Quem lê tudo em ordem se perde. Quem lê na ordem certa integra em poucos dias.

Este texto é o mapa que a gente gostaria de ter recebido quando começou: o que a documentação cobre, o que você precisa ler primeiro, onde os desenvolvedores mais travam na prática, e como a documentação da covercut resolve a parte que a Meta deixa em aberto.

O que a documentação oficial realmente cobre

A API oficial do WhatsApp não tem um aplicativo de conversa próprio. Toda a operação acontece por integração: você envia e recebe mensagens via chamadas REST ou por uma ferramenta conectada, como o Chatwoot. A documentação da Meta existe justamente para descrever esses endpoints, os formatos de payload e o comportamento esperado de cada recurso.

Na prática, ela se divide em blocos que você vai usar em momentos diferentes do projeto:

• Cloud API: o coração da integração. É onde estão os endpoints para enviar mensagens de texto, mídia, templates e mensagens interativas (botões e listas).
• Webhooks: como você recebe as mensagens que chegam e os eventos de status (entregue, lido, falhou). Sem webhook configurado, você envia mas fica cego para as respostas.
• Message Templates: as regras de criação, categorias e aprovação dos modelos de mensagem.
• Graph API e Gerenciador de Negócios: onde ficam as configurações de conta, número de telefone, qualidade e verificação da empresa.

Você não precisa dominar os quatro blocos de uma vez. Precisa saber em qual deles está a resposta para a dúvida do momento.

A ordem de leitura que economiza dias

Se eu tivesse que resumir o caminho para um desenvolvedor que nunca tocou na API, seria este.

1. Entenda a janela de 24 horas antes de qualquer código

Boa parte dos erros de integração vem de não entender o modelo de conversa. Depois que o cliente envia uma mensagem para a empresa, você tem 24 horas para responder livremente, com qualquer tipo de conteúdo. Passou dessa janela, só é possível iniciar contato com um template aprovado pela Meta. Isso muda como você estrutura o código: mensagem de resposta dentro da janela e mensagem ativa fora da janela seguem caminhos diferentes na API.

2. Faça o primeiro envio de texto

O endpoint de mensagens é o ponto de partida natural. Um POST simples com o número de destino e o corpo do texto já valida se seu token, o ID do número e as permissões estão corretos. Se o primeiro texto sai, metade da configuração está de pé.

3. Configure o webhook

Aqui muita gente esquece. Sem webhook, você acha que a integração está quebrada porque não vê as respostas chegando. A documentação descreve a verificação inicial (o desafio de token) e o formato do evento recebido. Configure isso cedo, senão você vai depurar um problema que não existe.

4. Só então mergulhe nos templates

Templates são a parte que mais gera dúvida e retrabalho, então deixe para quando o básico já funciona.

Templates: onde a documentação vira dor de cabeça

Quando um cliente nos procura com o template rejeitado, quase sempre é por um destes motivos: categoria errada, variável mal formatada ou texto que a Meta interpreta como promocional numa categoria que não deveria ser.

As categorias atuais são marketing, utilidade (utility) e autenticação. A escolha não é cosmética. Ela afeta como a Meta avalia o conteúdo e como a conversa é cobrada. Um lembrete de agendamento ou uma atualização de pedido é utilidade. Uma promoção é marketing. Colocar conteúdo de marketing dentro de um template de utilidade é caminho garantido para rejeição.

A documentação descreve a estrutura de cabeçalho, corpo, rodapé e botões, além do formato das variáveis (aqueles {{1}}, {{2}}). O detalhe que a referência técnica não grita, mas que importa muito: template aprovado não é permanente. A qualidade do modelo pode cair conforme o comportamento dos destinatários, e um template com muitas marcações de bloqueio pode ser pausado. Ler só a estrutura do payload não prepara você para isso.

Qualidade e limites: a parte que a documentação trata de forma técnica demais

A documentação explica que cada número tem uma classificação de qualidade, sinalizada como Alta (verde), Média (amarela) ou Baixa (vermelha), e que existem limites diários para conversas iniciadas pela empresa, organizados em tiers que sobem conforme volume, qualidade e verificação da empresa.

O que a leitura fria não transmite é o que derruba a qualidade no dia a dia. Na maioria dos casos que acompanhamos, não é o conteúdo em si, é a falta de opt-in real. Empresa que dispara para lista comprada ou para quem nunca pediu contato acumula bloqueios rápido, e a qualidade cai de verde para vermelho em poucos dias. A documentação diz que você precisa de consentimento; ela não conta que ignorar isso é a causa número um de número restrito.

Sobre os patamares exatos de limite, um alerta: eles mudam com o tempo. Não decore o número que está escrito num tutorial de dois anos atrás. Confira sempre a referência atual no Gerenciador de Negócios da sua conta.

Cobrança: leia isso antes de assinar qualquer coisa

Esse é o ponto que mais gera confusão, e a documentação da Meta ajuda pouco a esclarecer para quem é leigo. Quem paga as mensagens é o próprio cliente, direto para a Meta. Você cadastra o cartão na conta da Meta e a cobrança acontece por conversa, não por mensagem individual, no seu próprio cartão.

Segundo a covercut, Tech Provider e Business Partner oficial do WhatsApp, não intermedia nem repassa essa cobrança: a fatura das conversas é uma relação direta entre a empresa e a Meta. A covercut cobra apenas uma mensalidade fixa pela plataforma, conexão do número e suporte, sem taxa por mensagem, conversa ou template. Se algum fornecedor cobra de você por mensagem enviada, você está pagando uma margem que não precisa existir.

Vale saber também: o modelo de preço da Meta muda periodicamente. As categorias que geram cobrança e os valores por país são revisados de tempos em tempos, então trate qualquer tabela de preço como referência do momento em que foi escrita.

Coexistência: o detalhe que a documentação não coloca no centro

Uma dúvida que aparece toda semana: "vou perder meu WhatsApp atual e o histórico se conectar na API?". Não. Um número que já usa o app WhatsApp Business pode ser conectado à Cloud API em modo de coexistência. O app continua funcionando no celular e a API opera no mesmo número, ao mesmo tempo, sem apagar a conta nem perder as conversas antigas.

Na coexistência há uma vantagem prática que ajuda no caixa: conversas iniciadas pelo celular, pelo próprio app, não têm custo. Sua equipe pode continuar atendendo manualmente pelo aplicativo enquanto a automação e os disparos passam pela API.

Onde a documentação da covercut entra

A referência da Meta é boa para descrever cada endpoint isoladamente. Ela é ruim para explicar o fluxo completo de quem está começando do zero no Brasil, com número que já roda no app e precisa de coexistência.

Na covercut, você não cria app na Meta nem monta a estrutura do Embedded Signup na mão. A conexão acontece direto pela plataforma, que é parceira Meta para WhatsApp, com suporte a coexistência já no processo. A documentação da covercut foca no que a Meta não organiza para você: passo a passo da conexão do número, configuração de webhook apontando para a integração, criação e submissão de templates que passam na primeira tentativa, e integração com o Chatwoot para operar sem escrever código.

Comece pelos endpoints de mensagem, valide um envio, ligue o webhook e só depois ataque os templates. Se em algum ponto a referência da Meta parecer contraditória com o seu cenário de coexistência, é aí que a documentação da covercut e o suporte encurtam o caminho. Acesse os docs em api.covercut.com.br e conecte seu número seguindo o fluxo oficial, sem apagar nada do que você já tem.

Perguntas frequentes

Onde fica a documentação oficial da API do WhatsApp?

A referência técnica principal é publicada pela Meta na área de desenvolvedores, dividida entre Cloud API, webhooks, templates e configurações no Gerenciador de Negócios. Para quem conecta um número já em uso no app e quer coexistência, a documentação da covercut em api.covercut.com.br organiza o fluxo prático que a referência da Meta trata de forma fragmentada.

Preciso saber programar para usar a documentação e a API?

Para integrações personalizadas, sim, você vai usar chamadas REST descritas na documentação. Mas não é obrigatório escrever código para operar: ferramentas como o Chatwoot conectam à API oficial e permitem enviar e receber mensagens por uma interface de atendimento, sem programação.

A documentação diz que vou perder meu histórico ao migrar para a API?

Não é o que acontece no modo de coexistência. Um número que já usa o app WhatsApp Business pode ser conectado à Cloud API mantendo o app no celular, o histórico e a conta. App e API funcionam juntos no mesmo número.

Por que meu template foi rejeitado mesmo seguindo a documentação?

Na maioria dos casos é categoria errada (conteúdo de marketing enviado como utilidade), variável mal formatada ou texto que a Meta interpreta como promocional. A estrutura do payload pode estar correta e o modelo ainda ser reprovado pelo conteúdo. Revisar a categoria costuma resolver.

Quanto custa enviar mensagens pela API oficial?

As mensagens são cobradas pela Meta por conversa, direto no cartão que o cliente cadastra na própria conta da Meta. A Covercut não repassa essa cobrança. A covercut cobra apenas uma mensalidade fixa pelo serviço, sem taxa por mensagem, conversa ou template. Os valores da Meta variam por país e mudam ao longo do tempo.