Como Automatizar o WhatsApp de uma Empresa com a Cloud API
A janela de 24 horas, os modelos aprovados e o que a Meta exige: o que decide um projeto de WhatsApp antes de escreveres a primeira linha.
Nelson Barbosa
1. As duas vias, e porque a escolha decide tudo o resto
Há duas formas de ter WhatsApp num negócio, e confundi-las é o erro que faz perder semanas. A **aplicação WhatsApp Business** é gratuita, instala-se no telemóvel e serve para responder à mão. Tem respostas rápidas e etiquetas, mas não tem API: não se liga a um CRM, não recebe webhooks, não automatiza nada a sério. A **WhatsApp Cloud API**, da Meta, é a via para automatizar. É uma API HTTP alojada pela Meta, sem servidor de permeio. Dá para receber mensagens por webhook, responder por programa e integrar com o que quiseres. A diferença prática: na aplicação, o número vive no telemóvel; na Cloud API, o número passa a pertencer a uma conta de WhatsApp Business e **deixa de funcionar na aplicação**. Não há meio-termo, e a migração não se desfaz com um clique. Decide isto antes de escrever uma linha de código. Se o número que queres automatizar é o que a tua equipa usa no telemóvel, precisas de outro número.
2. A janela de 24 horas: a regra que trava toda a gente
Esta é a parte que quase nenhum tutorial explica, e é a que determina o que podes construir. Quando alguém te envia uma mensagem, abre-se uma **janela de 24 horas** durante a qual podes responder com texto livre — o que quiseres, quantas vezes quiseres. Passadas essas 24 horas sem nova mensagem do cliente, a janela fecha. Com a janela fechada, **só podes enviar modelos previamente aprovados pela Meta**. Nada de texto livre. E aprovar um modelo leva tempo: submetes o texto, a Meta revê, e pode recusar por motivos que vão de promoção agressiva a formatação. O que isto implica no desenho: - Um bot que responde a quem escreve primeiro é simples — está sempre dentro da janela - Um sistema que inicia conversas precisa de modelos aprovados para cada tipo de mensagem - Lembretes, confirmações e seguimentos têm de ser modelos, pensados com antecedência Desenha o fluxo à volta desta regra desde o início. Descobri-la depois de construir obriga a refazer.
3. O que a Meta exige antes de te deixar enviar
A conta não se abre em cinco minutos. Precisas de: **Uma conta Meta Business** com o negócio identificado. Para limites de envio mais altos e para o selo de verificação, a Meta pede documentação da empresa — certidão, morada, comprovativo de actividade. Um profissional independente consegue começar, mas com limites mais baixos. **Um número de telefone** que não esteja activo na aplicação WhatsApp, capaz de receber SMS ou chamada para o código de confirmação. **Um endpoint HTTPS** público para o webhook, com certificado válido. A Meta não entrega a endereços sem TLS nem a IPs. **Um modelo de mensagem aprovado**, se pretendes iniciar conversas. Os **limites de envio** começam baixos e sobem conforme a qualidade das tuas conversas — se muita gente te bloquear ou denunciar, descem. Não compres listas nem envies a quem não pediu: além de ilegal na UE sem consentimento, destrói a pontuação de qualidade e pode custar-te o número.
4. Receber mensagens: o webhook
A Meta valida o teu endpoint com um pedido `GET` que traz um desafio. Tens de devolver o valor de `hub.challenge` em texto simples, e só se o `hub.verify_token` corresponder ao que configuraste. Falhar isto é o motivo mais comum de a subscrição não activar. Depois da validação, as mensagens chegam por `POST`. Repara em dois detalhes que mordem: a Meta **repete** entregas quando não recebe um `200` depressa, por isso responde imediatamente e processa depois; e o payload vem encaixado em `entry[].changes[].value.messages[]`, não na raiz.
import os
from fastapi import FastAPI, Request, Response, BackgroundTasks
app = FastAPI()
VERIFY_TOKEN = os.environ["WA_VERIFY_TOKEN"]
@app.get("/webhook")
async def verificar(request: Request):
p = request.query_params
if p.get("hub.mode") == "subscribe" and p.get("hub.verify_token") == VERIFY_TOKEN:
# Texto simples, não JSON: a Meta compara byte a byte.
return Response(content=p.get("hub.challenge"), media_type="text/plain")
return Response(status_code=403)
@app.post("/webhook")
async def receber(request: Request, tarefas: BackgroundTasks):
body = await request.json()
for entry in body.get("entry", []):
for change in entry.get("changes", []):
for msg in change["value"].get("messages", []):
tarefas.add_task(tratar, msg["from"], msg.get("text", {}).get("body", ""))
# Confirmar já: a Meta repete a entrega se demorares.
return Response(status_code=200)5. Responder pela Cloud API
Enviar é um `POST` ao endpoint de mensagens do teu número, autenticado com um token. Dentro da janela de 24 horas envias texto livre; fora dela, só modelos. Guarda o `phone_number_id` e o token em variáveis de ambiente. O token dá acesso de envio em nome do teu negócio — tratado como qualquer outra credencial.
import os, httpx
PHONE_ID = os.environ["WA_PHONE_NUMBER_ID"]
TOKEN = os.environ["WA_TOKEN"]
BASE = f"https://graph.facebook.com/v21.0/{PHONE_ID}/messages"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
async def responder(para: str, texto: str):
"""Texto livre. Só funciona dentro da janela de 24 horas."""
async with httpx.AsyncClient(timeout=15) as c:
r = await c.post(BASE, headers=HEADERS, json={
"messaging_product": "whatsapp",
"to": para,
"type": "text",
"text": {"body": texto},
})
r.raise_for_status()
async def enviar_modelo(para: str, nome: str, variaveis: list[str]):
"""Fora da janela, só modelos previamente aprovados pela Meta."""
async with httpx.AsyncClient(timeout=15) as c:
r = await c.post(BASE, headers=HEADERS, json={
"messaging_product": "whatsapp",
"to": para,
"type": "template",
"template": {
"name": nome,
"language": {"code": "pt_PT"},
"components": [{
"type": "body",
"parameters": [{"type": "text", "text": v} for v in variaveis],
}],
},
})
r.raise_for_status()6. Guardar o estado da conversa
O WhatsApp não te dá sessões. Cada mensagem chega isolada, identificada apenas pelo número de telefone. Se o teu fluxo tem mais do que um passo, o estado é responsabilidade tua. O mínimo que funciona é uma tabela indexada pelo número, com o passo actual, os dados recolhidos até ali e a hora da última mensagem — essa última serve para saberes se a janela de 24 horas ainda está aberta. Duas armadilhas. Primeira: a mesma pessoa pode escrever várias vezes seguidas, e as entregas podem chegar fora de ordem; trata o estado com cuidado em concorrência. Segunda: as conversas ficam penduradas a meio. Define um tempo após o qual o estado expira, ou acumulas fluxos abandonados para sempre.
7. Acrescentar um modelo de linguagem
É aqui que a maioria dos projectos se estraga: ligam um modelo directamente ao WhatsApp e deixam-no responder a tudo. O que funciona é mais estreito. Usa o modelo para **classificar** a intenção, **extrair** dados de texto livre — datas, nomes, referências — e **reformular** respostas que já tens. Deixa a lógica de negócio em código. Três regras que evitam os problemas habituais: **Limita o âmbito no prompt e verifica a saída.** Um modelo que inventa preços ou compromete prazos cria-te uma obrigação com um cliente. **Prevê a passagem a humano.** Quando o modelo não sabe, ou quando a pessoa pede, encaminha. Um bot que não deixa falar com ninguém custa mais clientes do que os que converte. **Não reencaminhes dados sensíveis sem pensar.** Se a conversa inclui dados pessoais, estás a enviá-los ao fornecedor do modelo. Isso tem implicações no RGPD e deve constar da tua política de privacidade.
8. Construir de raiz ou usar uma plataforma
Existem plataformas que se colocam entre ti e a Cloud API — ManyChat, Twilio, 360dialog e outras. Fazem sentido em certos casos e não noutros. **Compensam** quando quem vai manter o fluxo não é programador, quando precisas de um construtor visual para a equipa mexer, ou quando queres começar hoje sem tratar de servidor nem webhook. **Não compensam** quando a lógica é específica do teu negócio, quando o volume torna a mensalidade mais cara que o custo próprio, ou quando precisas de integrações que a plataforma não tem. Há um custo menos visível: ficas dependente do modelo de dados dela. Migrar fluxos de uma plataforma para outra, ou para código próprio, costuma ser reescrever do zero. A meio caminho, ferramentas de automação como o n8n ou o Make ligam-se à Cloud API sem te prenderem a um construtor fechado — e o n8n podes alojar tu.
9. Consentimento e RGPD
WhatsApp é um canal pessoal, e a lei trata-o como tal. **Precisas de consentimento** para enviar mensagens a alguém que não te contactou primeiro. O consentimento tem de ser específico para este canal — ter o número de um cliente por causa de uma factura não autoriza mensagens comerciais. **Guarda a prova** de quando e como foi dado. Se a AEPD ou a CNPD perguntarem, a resposta é um registo, não uma afirmação. **Facilita a saída.** Uma instrução clara para deixar de receber, que funcione à primeira, e que respeites. **Diz que é um bot.** O Regulamento de IA da UE impõe transparência quando alguém interage com um sistema de IA. Uma frase na primeira mensagem resolve, e não custa conversão nenhuma — as pessoas percebem que é automático de qualquer forma. A tua política de privacidade deve dizer que dados recolhes por este canal, quanto tempo os guardas e com que fornecedores os partilhas.
10. Custos e quando não vale a pena
A Meta cobra pelo uso da Cloud API, e o modelo de preços já mudou mais do que uma vez — por conversa, por mensagem, com categorias diferentes conforme quem inicia. Não te dou valores porque envelhecem depressa: consulta a tabela oficial no dia em que decidires, e confirma a que se aplica ao teu país. Acresce o custo do que constróis à volta: servidor, manutenção, e o modelo de linguagem se usares um. **Quando não compensa:** se recebes poucas mensagens por dia, uma pessoa a responder na aplicação é mais barata e responde melhor. A automação começa a valer quando o volume repetitivo é constante, quando precisas de responder fora de horas, ou quando a mesma pergunta chega dezenas de vezes por semana. Antes de construir, conta durante uma semana quantas mensagens recebes e quantas são realmente repetidas. Se a maioria for específica, automatizar não te poupa tempo — muda-o de sítio.
Perguntas Frequentes (FAQ)
Posso automatizar o número que já uso na aplicação WhatsApp Business?
Podes migrá-lo para a Cloud API, mas deixa de funcionar na aplicação — não há uso simultâneo. Se a tua equipa responde a partir do telemóvel nesse número, usa outro para automatizar.
Quanto tempo demora a aprovação de um modelo de mensagem?
Varia, e pode ser recusado. Submete os modelos com antecedência em vez de na véspera de precisares deles, e evita texto promocional agressivo, que é o motivo de recusa mais comum.
O webhook tem de estar num servidor próprio?
Não. Serve qualquer endpoint HTTPS público com certificado válido — uma função serverless resolve. O que a Meta não aceita é HTTP simples nem endereços IP.
Preciso de empresa registada para usar a Cloud API?
Para começar e testar, não. Para limites de envio mais altos e para o selo de verificação, a Meta pede documentação do negócio. Um profissional independente consegue operar, com limites mais baixos.
O que acontece se a minha pontuação de qualidade descer?
Os limites de envio descem, e em casos persistentes o número pode ser restringido. A causa habitual é enviar a quem não pediu. Consentimento explícito e uma saída fácil protegem a pontuação melhor do que qualquer truque.