# Criar template

Fonte: https://apiwpp.com/docs/api/templates/criar-template
Seção: Templates
Atualizado em: 2026-09-28

`POST /connections/{id}/templates`

Cria um template de mensagem reutilizável na conexão: um corpo de texto com variáveis `{{nome}}` e, se quiser, uma mídia. Depois, envie pelo nome com `POST /connections/{id}/send`, passando `template` e os valores em `variables`. Escopo necessário: `templates:write`.

## Cabeçalhos

| Nome | Obrigatório | Descrição |
| --- | --- | --- |
| `Authorization` | sim | `Bearer <chave de API>`; ou envie a chave em `X-Api-Key`. |
| `Content-Type` | sim | `application/json` |

## Parâmetros de caminho

| Nome | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | `string · uuid` | sim | Identificador da conexão (o número). |

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | `string` | sim | Nome do template, único na conexão: letras sem acento, números, `_` e `-`. É guardado em minúsculas. |
| `body` | `string` | sim | Texto da mensagem, com variáveis no formato `{{nome}}`. Não pode ficar vazio nem só com espaços. |
| `media` | `object` | não | Mídia enviada junto com o texto, a partir de uma URL https pública. Opcional. |
| `media.type` | `string` | sim | Tipo da mídia: `image`, `video`, `audio`, `document` ou `sticker`. Valores: `"image"`, `"video"`, `"audio"`, `"document"`, `"sticker"`. |
| `media.url` | `string · uri` | sim | URL https pública do arquivo, baixada no momento de cada envio. Uma URL que não é https, que traz usuário e senha ou que aponta para um endereço privado ou interno é recusada já aqui, com `400`. (formato `^https://`) |
| `media.caption` | `string` | não | Legenda. Pode usar as mesmas `{{variáveis}}` do corpo: no envio, elas são substituídas pelos valores de `variables`, e uma variável que só aparece na legenda e não veio vira texto vazio. |
| `media.fileName` | `string` | não | Nome do arquivo, como o destinatário vê. |
| `media.mimetype` | `string` | não | Tipo MIME do arquivo (por exemplo, `application/pdf`). Obrigatório quando `type` é `document`. |
| `media.ptt` | `boolean` | não | Aceito para manter o mesmo formato do envio, mas o template não guarda este campo: o áudio de um template sai como arquivo de áudio, não como mensagem de voz. |
| `media.gifPlayback` | `boolean` | não | Aceito para manter o mesmo formato do envio, mas o template não guarda este campo: o vídeo de um template sai como vídeo comum. |

## Exemplo de requisição

### cURL

```bash
curl -X POST \
  https://api.apiwpp.com/connections/$CONNECTION_ID/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "confirmacao_consulta",
    "body": "Olá {{nome}}, até amanhã às {{hora}}."
  }'
```

### Node.js

```javascript
const res = await fetch(`https://api.apiwpp.com/connections/${connectionId}/templates`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'confirmacao_consulta',
    body: 'Olá {{nome}}, até amanhã às {{hora}}.',
  }),
})
const data = await res.json()
```

### PHP

```php
$response = Http::withToken($apiKey)
    ->post("https://api.apiwpp.com/connections/{$connectionId}/templates", [
        'name' => 'confirmacao_consulta',
        'body' => 'Olá {{nome}}, até amanhã às {{hora}}.',
    ]);
```

### Python

```python
import requests

response = requests.post(
    f"https://api.apiwpp.com/connections/{connection_id}/templates",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "confirmacao_consulta",
        "body": "Olá {{nome}}, até amanhã às {{hora}}.",
    },
)
```

## Respostas

| Código | Erro | Descrição |
| --- | --- | --- |
| 201 |  | O template criado: `id`, `connectionId`, `name` (em minúsculas), `body`, `media` (quando há mídia), `createdAt` e `updatedAt`. |
| 400 |  | O nome tem caracteres fora de letras, números, `_` e `-`, o corpo está vazio ou só com espaços, ou a URL da mídia é recusada (`Media URL must not carry credentials`, `Media URL points to a non-public address`), ou a mídia é um `document` sem `mimetype` (`media.mimetype is required for documents`). `error` diz qual foi. |
| 400 | `FST_ERR_VALIDATION` | O corpo (por exemplo, sem `name` ou sem `body`, `media` sem `type` ou sem `url`, um `type` fora da lista, ou `media.url` que não começa com `https://`) ou o `id` da conexão não segue o schema da operação; `message` diz o que está errado. |
| 401 |  | Sem chave de API, ou com uma chave inválida: desconhecida, revogada ou expirada. O corpo é `{"error": "Unauthorized"}`. |
| 403 |  | A chave não tem o escopo `templates:write`; a mensagem cita o escopo (`This credential lacks the templates:write scope`). |
| 404 |  | A conexão não existe ou não é de quem chama (`Connection not found`): o recurso de outra pessoa responde exatamente como um que não existe. |
| 409 |  | A conexão já tem um template com esse nome, sem diferenciar maiúsculas de minúsculas (`Template with this name already exists`). Para mudar um template existente, use `PUT /connections/{id}/templates/{name}`. |
| 429 |  | Requisições demais deste IP de origem (por padrão, 600 por minuto), ou autenticações com falha demais (por padrão, 20 a cada 5 minutos): espere os segundos de `Retry-After`. Veja [Limites](https://apiwpp.com/docs/referencia/limites). Cabeçalhos: `Retry-After`. |

### 201 Created

```json
{
  "id": "7a0b3c4d-5e6f-4a7b-8c9d-2e3f4a5b6c7d",
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "name": "confirmacao_consulta",
  "body": "Olá {{nome}}, até amanhã às {{hora}}.",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
```

## Detalhes

Cada template pertence a uma conexão (o número): outra conexão não enxerga os templates desta. Excluir a conexão exclui os templates dela.

O nome aceita só letras sem acento, números, `_` e `-`, e é guardado em minúsculas: `Confirmacao_Consulta` vira `confirmacao_consulta`. Ele é único na conexão, sem diferenciar maiúsculas de minúsculas, e não muda depois: para renomear, crie um template novo e exclua o antigo.

Uma variável é `{{` + um nome que começa com letra ou `_` e continua com letras, números ou `_` + `}}`. No envio, toda variável do corpo é obrigatória: faltando alguma em `variables`, o envio responde `400` com a lista em `missingVariables`. Veja [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens).

Guia: [Enviar mensagens](https://apiwpp.com/docs/guias/enviar-mensagens).
