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 criá-los, gerenciá-los e enviá-los.

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. Os status são atualizados da Meta automaticamente sempre que você lê os modelos. Um modelo REJECTED traz o rejected_reason da Meta; um aprovado, seu quality_score (GREEN, YELLOW, RED, UNKNOWN).

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

Tarefa	Endpoint
Listar (filtra por status)	`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 pela API; cabeçalhos de imagem, vídeo e documento podem ser criados no portal), 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.

Enviando um modelo

POST /api/v1/messages/send-template envia um modelo APPROVED. Forneça os valores das variáveis por componente. Modelos posicionais ({{1}}, {{2}}) recebem arrays:

curl -X POST https://fiwano.com/api/v1/messages/send-template \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "template_name": "order_confirmation",
    "language": "en_US",
    "recipient": "1234567890",
    "variables": {
      "header": ["Summer Sale"],
      "body": ["Pablo", "ORD-123", "25%"],
      "buttons": [{"index": 0, "value": "promo25"}]
    }
  }'

Modelos nomeados ({{customer_name}}) recebem objetos:

  -d '{
    "channel_id": "a1b2c3d4e5f67890",
    "template_name": "welcome_message",
    "language": "en_US",
    "recipient": "1234567890",
    "variables": {"body": {"customer_name": "Pablo", "order_number": "ORD-123"}}
  }'

Omita variables por completo se o modelo não tiver nenhuma.

Cabeçalho de mídia. Quando o cabeçalho do modelo é imagem, vídeo ou documento (variables.header_media do modelo), passe o arquivo como URL HTTPS em header_media_url. A Meta o baixa como nos envios de mídia, então esse envio leva o tempo de um envio de mídia.

A resposta é a mesma dos envios de texto e mídia: guarde o message_id (um UUID da Fiwano) para correlacionar os webhooks de entrega. Um envio de modelo nunca é repetido automaticamente — veja Entrega e novas tentativas.

Autenticação (códigos únicos)

A Meta define o texto de um modelo AUTHENTICATION ("123456 is your verification code."); você escolhe os extras e adiciona um botão de copiar código:

"components": [
  {"type": "BODY", "add_security_recommendation": true},
  {"type": "FOOTER", "code_expiration_minutes": 10},
  {"type": "BUTTONS", "buttons": [{"type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code"}]}
]

FOOTER é opcional. Botões one-tap e zero-tap exigem um app Android — crie-os no WhatsApp Manager; a Fiwano os envia como qualquer outro modelo.

Envie o código uma vez — ele também preenche o botão de copiar código (até 15 caracteres):

  -d '{"channel_id": "a1b2c3d4e5f67890", "template_name": "login_code",
       "language": "en_US", "recipient": "1234567890",
       "variables": {"body": ["482913"]}}'

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 e button_id o seu id, 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.

Defina o id de um botão de resposta rápida no envio, em variables.buttons: {"index": 0, "id": "confirm:ORD-123"} (até 256 caracteres). Sem id, button_id é o texto do botão. value continua sendo a variável de um botão de URL ou de copiar código.

Dentro da janela de 24 horas, botões, cards e listas podem ser enviados sem modelo — veja Mensagens interativas.