# Modelos

> Modelos aprovados do WhatsApp.

Modelos (templates) são mensagens aprovadas pela Meta. Na API oficial do WhatsApp, são a única forma de falar com quem não mandou mensagem nas últimas 24 horas.

- [`GET /modelos`](https://docs.forsi.com.br/api/modelos/listar-modelos) lista os modelos de cada caixa com nome, idioma, categoria, estado e texto. Filtre por `estado=APPROVED` para ver só os que podem sair.
- Para enviar, use [`POST /mensagens`](https://docs.forsi.com.br/api/mensagens/enviar-mensagem) com `tipo: "modelo"` e o `modelo` (id, ou nome + idioma) com as variáveis em `corpo`, o `cabecalho` e os `botoes`, quando houver.
- Modelos só saem por caixas conectadas à API oficial (`422 modelo_sem_api_oficial`).

**Códigos de erro comuns aqui**: `caixa_inexistente` (todos em [Erros](https://docs.forsi.com.br/erros)).

## GET /modelos — Listar modelos do WhatsApp

- URL: `GET https://chat.forsi.com.br/api/v1/modelos`
- Acesso: escopo `modelos:ler` · módulo do plano: API
- Sucesso: `200`, `{"dados": ...}` com lista de `Modelo`
- Página: https://docs.forsi.com.br/api/modelos/listar-modelos (Markdown: https://docs.forsi.com.br/api/modelos/listar-modelos.md)

Modelos da API oficial sincronizados com a Meta, com as variáveis de cada um.

**Parâmetros de consulta (query string)**

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `estado` | string | não | APPROVED, PENDING, REJECTED... até 30 caracteres |
| `caixa_id` | uuid | não |  |

**Exemplo (curl)**

```bash
curl "https://chat.forsi.com.br/api/v1/modelos?estado=APPROVED" \
  -H "Authorization: Bearer $FORSI_CHAVE"
```

**Resposta `200` (exemplo)**

```json
{
  "dados": [
    {
      "id": "2eabdd6d-7cb0-4c12-9da3-8f9441056099",
      "nome": "lembrete_consulta",
      "idioma": "pt_BR",
      "categoria": "UTILITY",
      "estado": "APPROVED",
      "caixa_id": "7a9d53e9-9d1b-4122-923b-fac67958f445",
      "formato_parametros": "positional",
      "variaveis": ["texto"],
      "texto": "Olá {{1}}, sua consulta é amanhã às {{2}}.",
      "componentes": [],
      "atualizado_em": "2026-10-04T13:05:12.481Z"
    }
  ]
}
```

**Erros**: `401`, `403`, `422`, `429` (formato e códigos em "Erros"; códigos desta seção no início dela).

## Objetos das respostas

Campos de cada objeto devolvido em `dados`. Campos novos podem aparecer: ignore os que não conhecer.

### Modelo

| Campo | Tipo | Obrigatório | Notas |
| --- | --- | --- | --- |
| `id` | uuid | não |  |
| `nome` | string | não |  |
| `idioma` | string | não |  |
| `categoria` | string | não |  |
| `estado` | string | não | ex.: APPROVED |
| `caixa_id` | uuid | não |  |
| `formato_parametros` | string | não |  |
| `variaveis` | lista de string | não |  |
| `texto` | string | não |  |
| `componentes` | array | não |  |
| `atualizado_em` | data e hora ISO 8601 | não |  |

---

Página: https://docs.forsi.com.br/api/modelos · Índice: https://docs.forsi.com.br/llms.txt · Tudo num arquivo: https://docs.forsi.com.br/llms-full.txt