Modelos do WhatsApp

O WhatsApp exige modelos pré-aprovados para iniciar uma conversa fora da janela de 24 horas (veja Capacidades). Modelos são exclusivos do WhatsApp e exigem uma licença Pro. Esta página trata de gerenciá-los; para enviar um modelo aprovado, veja Enviando → Mensagens de modelo.

Ciclo de vida

Create → PENDING (revisão da Meta, ~24h) → APPROVED (pronto para envio)
                                          → REJECTED (corrija e reenvie)

A Meta pode depois pausar (PAUSED, baixa qualidade) ou desativar (DISABLED) um modelo aprovado. Um envio então falha com error_code 132015 / 132016; listar os modelos com a sincronização padrão mostra o status atual.

Os modelos pertencem à WhatsApp Business Account (WABA) do canal. Gerencie-os por estes endpoints — os schemas completos de request/response estão na Referência da API:

Tarefa	Endpoint
Listar (filtra por status; sincroniza da Meta por padrão)	`GET /api/v1/channels/{id}/templates`
Obter um (componentes + definições de variáveis)	`GET /api/v1/channels/{id}/templates/{template_id}`
Criar (→ enviado à Meta, começa em `PENDING`)	`POST /api/v1/channels/{id}/templates`
Atualizar componentes	`PUT /api/v1/channels/{id}/templates/{template_id}`
Excluir	`DELETE /api/v1/channels/{id}/templates/{template_id}`

Criando um modelo

Um modelo é um name + category (MARKETING, UTILITY ou AUTHENTICATION) + language + components. BODY é obrigatório; HEADER (somente texto), FOOTER e BUTTONS são opcionais. As variáveis são {{1}}, {{2}} (posicionais) ou {{name}} (nomeadas) — a Meta exige valores de example para a revisão.

curl -X POST https://fiwano.com/api/v1/channels/a1b2c3d4e5f67890/templates \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "category": "UTILITY",
    "language": "en_US",
    "components": [
      {"type": "BODY", "text": "Hi {{1}}, your order {{2}} is confirmed.",
       "example": {"body_text": [["Pablo", "ORD-123"]]}}
    ],
    "parameter_format": "positional"
  }'

Regras importantes

Editar um modelo aprovado o reenvia para revisão (volta a PENDING) e é limitado pela Meta: no máximo 10 edições a cada 30 dias, 1 a cada 24 horas. Você não pode alterar a categoria de um modelo aprovado.
Excluir um modelo aprovado bloqueia seu nome por 30 dias — você não pode recriar um modelo com o mesmo nome até lá (restrição da Meta).
Criar é limitado a ~100 modelos por WABA por hora.

Quando um modelo está APPROVED, envie-o com POST /api/v1/messages/send-template.

Botões

BUTTONS pode conter botões URL, de telefone e QUICK_REPLY. Quando um destinatário toca em um botão de resposta rápida, seu webhook recebe um message.received comum de type: "text" cujo text é o rótulo do botão, com reply_to.message_id igual ao message_id que você recebeu de send-template — assim você sabe qual botão foi escolhido e a qual envio ele responde. Mensagens interativas avulsas com botões de resposta ou listas (fora de templates) ainda não podem ser enviadas, mas os toques nelas são recebidos da mesma forma.