# WhatsApp Business Platform: Cloud API e templates

> 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.

- URL canônico: https://www.broadnet.me/pt/reference/whatsapp-business-cloud-api
- Idioma: pt
- Última atualização: 2026-07-18
- Editor: BroadNet (https://www.broadnet.me)

Como funciona a WhatsApp Business Platform: Cloud API vs On-Premises API, mensagens de template (HSM) vs mensagens de sessão, a janela de apoio ao cliente de 24 horas, as categorias marketing/utility/authentication, webhooks, níveis de qualidade do número e opt-in.

## 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.

*Cloud API vs On-Premises API*

| 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.

*Cloud API: enviar um template utility aprovado*

```json
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.

*Categorias de template do WhatsApp*

| 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.

*Webhook de entrada: a mensagem do utilizador abre a janela de 24 horas*

```json
{
  "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.

*Classificação de qualidade e níveis de mensagens*

| 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.

## Fontes

- [WhatsApp Business Platform — Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api)
- [WhatsApp — Message templates and categories](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates)
- [WhatsApp — Per-message pricing and the 24-hour window](https://developers.facebook.com/docs/whatsapp/pricing)

## Relacionados

- [WhatsApp Business API](https://www.broadnet.me/pt/products/whatsapp-business-api)
- [RCS vs SMS vs WhatsApp](https://www.broadnet.me/pt/reference/rcs-vs-sms-vs-whatsapp-channels)
- [Cartões ricos e mensagens interativas](https://www.broadnet.me/pt/reference/rich-cards-and-interactive-messaging)
- [Fallback e orquestração de canais](https://www.broadnet.me/pt/reference/channel-fallback-and-orchestration)
- [Omnicanal](https://www.broadnet.me/pt/products/omnichannel)
- [Programadores](https://www.broadnet.me/pt/developers)