API oficial do WhatsApp (Cloud API): guia para começar

Existe um ponto em que o WhatsApp Business no celular para de dar conta: quando o pedido precisa virar mensagem sozinho, quando o atendimento não cabe em quatro aparelhos, quando alguém pergunta “dá para integrar com o nosso sistema?”.

Daí em diante o assunto é a API oficial. Este guia explica o que ela é de fato, o que a Meta exige antes de liberar, como sai a primeira mensagem e onde os projetos costumam travar.

O que é a API oficial

A WhatsApp Business Platform — o nome oficial — não é um aplicativo. Não tem tela, não tem lista de conversas, não roda em celular. É uma interface HTTP: seu sistema faz uma requisição e o WhatsApp entrega a mensagem.

Quem monta a interface é você, ou a plataforma de atendimento que você contratar. Isso é a fonte da confusão mais comum: a maioria das empresas não fala com a API diretamente, fala com um fornecedor que fala com a API.

Cloud API ou On-Premises

Houve duas formas de hospedar a API. Hoje só uma importa.

Quando a API vale a pena — e quando não

Ela custa dinheiro por mensagem e exige desenvolvimento. Não é upgrade natural de quem usa o app.

• Vale quando a mensagem precisa sair de um sistema: confirmação de pedido, código de acesso, aviso de entrega, lembrete de consulta.
• Vale quando há mais de quatro pessoas atendendo, ou quando você precisa de fila, histórico por atendente e relatório de tempo de resposta.
• Vale quando o WhatsApp precisa conversar com o CRM, o ERP ou a plataforma de e-commerce.
• Não vale para quem atende de dez a cem conversas por dia sozinho: o WhatsApp Business gratuito faz isso melhor e de graça.
• Não vale como atalho para disparo em massa. A API é o lugar mais fiscalizado do WhatsApp — o assunto está em disparo em massa.

A API resolve automação e escala. Ela não resolve atendimento ruim, e custa mais caro para fazer a mesma coisa que o aplicativo já fazia.

O que a Meta exige antes

1. 1

   Uma conta no Meta Business

   É o painel onde vivem a conta comercial do WhatsApp (WABA), os números e os métodos de pagamento. Se sua empresa já anuncia no Facebook ou no Instagram, ela provavelmente já existe.

2. 2

   Um número de telefone livre

   O número não pode estar registrado no WhatsApp comum nem no Business. Se estiver, precisa ser apagado da conta antes — e o histórico de conversas não vai junto. Por isso a maioria usa um número novo.

3. 3

   Um app no painel de desenvolvedores

   Do tipo Business, com o produto WhatsApp adicionado. É o que gera o identificador do número (phone-number-id) e o token de acesso.

4. 4

   Nome de exibição aprovado

   O nome que o cliente vê passa por revisão da Meta e precisa ter relação com a empresa. Nome genérico como “Atendimento” costuma ser recusado.

5. 5

   Verificação da empresa

   Envio de documentos (no Brasil, cartão CNPJ e comprovantes). Sem ela você fica preso no limite mais baixo de envio e não consegue crescer.

A primeira mensagem

Com o app criado, a Meta libera um número de teste e um token temporário. Dá para enviar para até cinco destinatários cadastrados, sem custo, antes de conectar o número real.

curl -X POST \
  "https://graph.facebook.com/v21.0/SEU_PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en_US" }
    }
  }'

Repare que o primeiro envio é um template, não um texto livre. Isso não é detalhe da documentação — é a regra central da plataforma.

A regra que organiza tudo: a janela de 24 horas

Você não pode escrever o que quiser para quem quiser. O que vale depende de quem falou por último.

Template é uma mensagem escrita antes, submetida à Meta e aprovada, com espaços para variáveis ({{1}}, {{2}}). A aprovação leva de minutos a algumas horas e reprova promessa exagerada, erro de português e variável sem exemplo. Como escrever um que passe: templates de mensagem.

Receber mensagens: webhooks

Enviar é metade. Para receber, você registra uma URL pública e a Meta passa a mandar cada evento para lá — mensagem recebida, entrega confirmada, mensagem lida.

Isso significa que a API exige um servidor sempre no ar. Não existe modo “consulta quando eu quiser”. É o requisito que costuma surpreender quem imaginava algo mais simples. O funcionamento está em webhooks do WhatsApp.

Limites de envio

Conta nova não sai enviando para todo mundo. A Meta trabalha com faixas, e você sobe conforme o volume e a qualidade das suas mensagens.

• A faixa inicial permite iniciar conversa com um número limitado de clientes distintos por dia.
• As faixas seguintes multiplicam esse teto, até chegar em ilimitado.
• Subir depende de verificação da empresa e de manter a qualidade em nível bom.
• A qualidade cai com bloqueio e denúncia de quem recebe. Cair demais derruba a faixa — e pode restringir o número.

Quanto custa

A hospedagem da Cloud API não é cobrada. Cobra-se por mensagem enviada, e o preço varia conforme a categoria do template e o país de quem recebe.

• Marketing — promoção, novidade, carrinho abandonado. É a categoria mais cara.
• Utilidade — confirmação de pedido, aviso de entrega, segunda via. Mais barata.
• Autenticação — código de acesso de uso único.
• Serviço — resposta dentro da janela aberta pelo cliente. Não é cobrada.

Como isso vira conta no fim do mês, com o cálculo por cenário, está em quanto custa a API do WhatsApp.

Sozinho ou com fornecedor

Perguntas frequentes

Resumo

• Cloud API é o caminho atual; On-Premises está sendo encerrado.
• Exige conta no Meta Business, número livre, nome aprovado e verificação da empresa.
• Fora da janela de 24 horas só sai template aprovado.
• Receber mensagem exige webhook, ou seja, um servidor sempre no ar.
• A hospedagem é gratuita; paga-se por mensagem, e bloqueio de usuário é o que derruba a conta.
• Mantenha a conta comercial e o número no seu Meta Business, não no do fornecedor.