A WhatsApp Business Platform envia mensagens através da Cloud API (alojada pela Meta) ou da antiga On-Premises API. As mensagens iniciadas pela empresa têm de usar templates pré-aprovados numa categoria (marketing, utility, authentication); as mensagens de sessão em texto livre só são permitidas dentro de uma janela de apoio ao cliente de 24 horas aberta pela última mensagem do utilizador. O opt-in é obrigatório.
Cloud API vs On-Premises API
A WhatsApp Business Platform expõe duas APIs com o mesmo modelo de mensagens mas com alojamento diferente. A Cloud API é alojada pela Meta: uma empresa (ou o seu fornecedor de soluções) chama um endpoint REST em estilo Graph associado a um ID de número de telefone, sem cliente local para executar. A On-Premises API é um cliente em contentor que a própria empresa aloja, historicamente usado por razões de residência de dados ou de latência; a Meta designou-a para descontinuação a favor da Cloud API. Ambas são governadas pelas mesmas regras — templates, janela de 24 horas, categorias, qualidade e opt-in — pelo que a escolha é operacional (quem aloja) e não funcional.
| Propriedade | Cloud API | On-Premises API |
|---|---|---|
| Alojamento | Alojado pela Meta, sem cliente para executar | Cliente em contentor alojado pela empresa |
| Endpoint | Graph REST num ID de número de telefone | Endpoint REST do cliente local |
| Atualizações | Gerido por Meta | A empresa mantém as versões para clientes |
| Status | Recomendado, ativamente desenvolvido | Previsto para descontinuação |
| Regras (modelos/janela/qualidade) | Idêntico | Idêntico |
Mensagens de template (HSM) vs mensagens de sessão
O WhatsApp separa os dois sentidos das mensagens de negócio. Uma empresa não pode abordar a frio um utilizador com conteúdo em texto livre: qualquer mensagem iniciada pela empresa tem de ser um template de mensagem — historicamente chamado Highly Structured Message (HSM) — que tenha sido submetido e aprovado antecipadamente pelo WhatsApp, com marcadores de variáveis nomeados e uma categoria declarada. Assim que o utilizador responde, abre-se uma janela de apoio ao cliente de 24 horas em que a empresa pode enviar mensagens de sessão em texto livre (texto, multimédia, interativas) sem template. Fora dessa janela, a empresa tem novamente de começar com um template aprovado. Esta regra de "template primeiro" é a restrição central da plataforma.
POST https://graph.facebook.com/v20.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "template",
"template": {
"name": "order_shipped",
"language": { "code": "en_US" },
"components": [
{ "type": "body",
"parameters": [ { "type": "text", "text": "4021" } ] }
]
}
}A janela de apoio ao cliente de 24 horas
A janela de 24 horas é o mecanismo que controla o envio em texto livre. Abre (ou reabre) cada vez que o utilizador envia uma mensagem à empresa, e dura 24 horas a contar dessa última mensagem do utilizador. Dentro da janela, a empresa pode responder com qualquer tipo de mensagem permitido — texto simples, multimédia, botões interativos ou listas — sem usar um template. Quando a janela fecha, os envios em texto livre são rejeitados e a empresa tem de reengajar com um template aprovado (sujeito à categoria e, no marketing, a limites por utilizador). Tanto a tarifação por sessão como a mais recente tarifação por mensagem dependem de o envio cair dentro ou fora desta janela.
Categorias de mensagem: marketing, utility, authentication
Cada template recebe uma categoria que governa como pode ser usado e como é tarifado. Os templates utility referem-se a uma transação ou evento de conta específico e acordado (atualizações de encomenda, lembretes de marcação, extratos). Os templates authentication entregam palavras-passe de utilização única e verificação, com um formato restrito. Os templates marketing transportam promoções, ofertas e reengajamento e são os mais rigidamente governados — sujeitos a opt-in do utilizador, sinais de qualidade e limites de frequência. O WhatsApp analisa o conteúdo do template face à categoria declarada na aprovação e pode recategorizá-lo; enviar conteúdo de marketing sob um rótulo utility é uma causa comum de rejeição ou de dano à qualidade.
| Categoria | Finalidade | Notas |
|---|---|---|
| Utilidade | Atualizações de transações/contas que o utilizador espera | Vinculado a uma ação ou acordo específico |
| Autenticação | Palavras-passe de uso único, verificação | Formato restrito; focado em OTP |
| Marketing | Promoções, ofertas, reengajamento | Opt-in rigoroso, governança de qualidade e frequência |
| Serviço (sessão) | Respostas em formato livre na janela de 24h | Não requer modelo; não iniciado pela empresa |
Webhooks: mensagens de entrada e estado de entrega
A plataforma é assíncrona e orientada a callbacks. Uma empresa configura um URL de webhook para o qual o WhatsApp publica dois tipos de eventos: mensagens de entrada (as respostas do utilizador, multimédia, toques em botões, localização) e notificações de estado das mensagens de saída, que progridem por sent, delivered, read e — em caso de falha — failed com um código de erro. As confirmações de leitura e o ciclo de vida da mensagem surgem aqui, e a chegada de um evento de mensagem de entrada é exatamente o que abre ou renova a janela de 24 horas. Uma integração robusta confirma os webhooks rapidamente e concilia o estado de entrega com o seu próprio repositório de mensagens, tal como uma plataforma de SMS concilia os DLR.
{
"entry": [{ "changes": [{ "value": {
"messaging_product": "whatsapp",
"messages": [{
"from": "15551234567", "id": "wamid.HBg...",
"timestamp": "1752796800",
"type": "text", "text": { "body": "Where is my order?" }
}]
} }] }]
}Qualidade do número, níveis e opt-in
Cada número de telefone de negócio tem uma classificação de qualidade (apresentada como alta/média/baixa, muitas vezes colorida a verde/amarelo/vermelho) derivada de como os utilizadores reagem às suas mensagens — bloqueios e denúncias fazem-na descer. A qualidade controla o nível do limite de mensagens, que limita quantos utilizadores únicos um número pode iniciar conversas num período móvel de 24 horas; os níveis sobem (por exemplo 250, 1K, 10K, 100K e depois ilimitado) à medida que a qualidade e o volume se sustentam, e descem se a qualidade cair. Na base de tudo está o opt-in: o WhatsApp exige que as empresas obtenham e registem o consentimento explícito do utilizador, recolhido em qualquer canal, antes de enviar. Más práticas de opt-in surgem rapidamente como bloqueios, qualidade degradada e um nível limitado.
| Signal | Significado | Efeito |
|---|---|---|
| Qualidade: alta (verde) | Poucos bloqueios/denúncias | Elegível para subir de nível |
| Qualidade: média (amarelo) | Algumas críticas negativas | Em observação; dimensionamento pausado |
| Qualidade: baixa (vermelho) | Muitos bloqueios/denúncias | Risco de rebaixamento de nível ou sinalização |
| Tier (250 / 1K / 10K / 100K / ∞) | Utilizadores únicos iniciados por 24 horas | Elevado com qualidade + volume sustentados |
| Opt-in | Consentimento do utilizador registado | Obrigatório antes de qualquer envio iniciado pela empresa |
Perguntas frequentes
Qual é a diferença entre a Cloud API e a On-Premises API?
Ambas usam o mesmo modelo de mensagens do WhatsApp, mas a Cloud API é alojada pela Meta (chama um endpoint REST, nada para executar), ao passo que a On-Premises API é um cliente em contentor que a própria empresa aloja. A Meta designou a On-Premises API para descontinuação a favor da Cloud API. Templates, janela de 24 horas, categorias e regras de qualidade aplicam-se de forma idêntica a ambas.
O que é um template de mensagem do WhatsApp (HSM)?
Um template — historicamente uma Highly Structured Message — é conteúdo pré-aprovado com marcadores de variáveis nomeados e uma categoria declarada. Qualquer mensagem do WhatsApp iniciada pela empresa tem de ser um template; o conteúdo em texto livre só é permitido dentro da janela de apoio ao cliente de 24 horas aberta pela resposta de um utilizador.
O que é a janela de apoio ao cliente de 24 horas?
É o período, com duração de 24 horas a contar da última mensagem do utilizador para a empresa, durante o qual a empresa pode enviar mensagens de sessão em texto livre sem template. Quando fecha, os envios em texto livre são rejeitados e a empresa tem de reengajar com um template aprovado. Os eventos de webhook de entrada abrem ou renovam a janela.
Quais são as categorias de mensagem do WhatsApp?
Os templates são categorizados como utility (atualizações de transação/conta que o utilizador espera), authentication (palavras-passe de utilização única e verificação) ou marketing (promoções e reengajamento, os mais rigidamente governados). As respostas em texto livre dentro da janela são mensagens de serviço. A categoria governa o uso permitido e a tarifação, e o WhatsApp analisa o conteúdo face à categoria declarada.
O que determina o limite de mensagens de um número WhatsApp?
O nível de mensagens limita quantos utilizadores únicos um número pode iniciar conversas por período móvel de 24 horas (por exemplo 250, 1K, 10K, 100K e depois ilimitado). Os níveis sobem com qualidade e volume sustentados e descem se a qualidade cair. A qualidade é uma classificação alta/média/baixa determinada pelos bloqueios e denúncias dos utilizadores.
Preciso de opt-in para enviar mensagens a utilizadores no WhatsApp?
Sim. O WhatsApp exige consentimento explícito e registado do utilizador — que pode ser recolhido em qualquer canal — antes de uma empresa enviar mensagens. Um opt-in fraco surge rapidamente como bloqueios e denúncias, que baixam a classificação de qualidade do número e podem limitar ou despromover o seu nível de mensagens.
Especificações de origem
Os padrões publicados nos quais esta página se baseia. Abre num novo separador.