# Templates: criar e enviar

> Crie templates do WhatsApp com POST /v1/templates, acompanhe a aprovação da Meta e envie com type template, com variáveis, cabeçalho de mídia e botão de URL.

Template é uma mensagem com texto fixo e variáveis, **aprovada pela Meta antes de poder ser usada**. No WhatsApp ele é o único jeito de iniciar uma conversa ou de falar com o contato depois que a janela de 24 horas fechou (veja [Janelas de conversa](/start/concepts/#janelas-de-conversa)). Dentro da janela, você pode mandar [texto livre](/send/text/) ou qualquer outro tipo.

Esta página cobre templates de qualquer categoria. Para códigos de verificação, veja [Templates de autenticação](/guides/authentication-templates/); para disparos em massa, [Campanhas](/guides/campaigns/).

## Criar

`POST /v1/templates` cria o template na conta do WhatsApp da conexão e o envia para a revisão da Meta. Precisa de uma chave com a permissão `templates`. No painel: **Templates → Novo template**.

| Campo | Regra |
| --- | --- |
| `connection_id` | Opcional com chave de conexão (`mjc_…`); obrigatório com chave de organização (`mj_…`) |
| `name` | Letras minúsculas, números e `_` |
| `language` | Código da Meta, como `pt_BR`, `en_US` ou `es` |
| `category` | `MARKETING`, `UTILITY` ou `AUTHENTICATION` |
| `parameter_format` | Opcional: `POSITIONAL` (`{{1}}`) ou `NAMED` |
| `components` | Lista com no máximo um de cada: `HEADER`, `BODY` (com `text`, obrigatório), `FOOTER` e `BUTTONS` |

- `HEADER` aceita `format` `TEXT`, `IMAGE`, `VIDEO`, `DOCUMENT` ou `LOCATION`.
- `BUTTONS` aceita botões `QUICK_REPLY`, `URL`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`, `FLOW`, `CATALOG`, `MPM` e `VOICE_CALL`.
- Os componentes seguem o formato de criação da Meta. Variáveis no texto precisam de um exemplo (`example`), como no corpo abaixo.
- **Cabeçalho de mídia** (`IMAGE`, `VIDEO`, `DOCUMENT`) exige um arquivo de exemplo: `components.HEADER.example.header_handle`, o identificador devolvido pelo upload retomável da Meta. Sem ele a chamada volta `400` [`validation_failed`](/errors#validation_failed). No painel, o Messajo faz esse upload quando você escolhe o arquivo.

Exemplo: corpo com duas variáveis, rodapé e um botão de resposta rápida.

**cURL**

```bash
curl https://api.messajo.com/v1/templates \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "connection_id": "conn_...",
  "name": "pedido_enviado",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Obrigado por comprar com a gente"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Falar com a loja"
        }
      ]
    }
  ]
}'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const template = await messajo.templates.create({
  connection_id: "conn_...",
  name: "pedido_enviado",
  language: "pt_BR",
  category: "UTILITY",
  components: [
    {
      type: "BODY",
      text: "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
      example: {
        body_text: [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      type: "FOOTER",
      text: "Obrigado por comprar com a gente"
    },
    {
      type: "BUTTONS",
      buttons: [
        {
          type: "QUICK_REPLY",
          text: "Falar com a loja"
        }
      ]
    }
  ]
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/templates

```json
{
  "connection_id": "conn_...",
  "name": "pedido_enviado",
  "language": "pt_BR",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{1}}, seu pedido {{2}} saiu para entrega.",
      "example": {
        "body_text": [
          [
            "Ana",
            "12345"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Obrigado por comprar com a gente"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Falar com a loja"
        }
      ]
    }
  ]
}
```

A resposta é `201` com o template: `id` (`tpl_…`), `status`, `category`, `components` e `rejected_reason` quando houver recusa.

## Ciclo de vida

Depois de criado, o template vai para a revisão da Meta. Cada mudança de status chega no evento [`template.status`](/webhooks/events/); consulte também `GET /v1/templates/{id}`.

| Status | O que significa |
| --- | --- |
| `PENDING` | Em revisão. Ainda não dá para enviar. |
| `APPROVED` | Aprovado. Pode ser enviado. |
| `REJECTED` | A Meta recusou; o motivo vem em `rejected_reason`. Edite e reenvie para revisão. |
| `PAUSED` | A Meta pausou por baixa qualidade. Não envia até voltar. |
| `DISABLED` | A Meta desativou. |

Há ainda `IN_APPEAL`, `PENDING_DELETION`, `DELETED`, `ARCHIVED`, `LIMIT_EXCEEDED`, `LOCKED`, `FLAGGED` e `REINSTATED`, que vêm da Meta como estão.

- **Listar e consultar:** `GET /v1/templates` (com filtros e paginação) e `GET /v1/templates/{id}`, com a permissão `read`.
- **Editar:** `PATCH /v1/templates/{id}` troca `components` ou `category`. A Meta só deixa editar template `APPROVED`, `REJECTED` ou `PAUSED`, e um template aprovado não troca de categoria.
- **Excluir:** `DELETE /v1/templates/{id}` exclui na Meta e no Messajo.
- **Sincronizar:** o Messajo relê os templates da Meta todo dia. `POST /v1/templates/sync` faz a leitura na hora; o template que sumiu da Meta fica marcado como excluído.

## Enviar

`POST /v1/messages` com `type: "template"`:

| Campo | Regra |
| --- | --- |
| `template.name` | Nome do template, de 1 a 512 caracteres |
| `template.language` | Código do idioma, como `pt_BR` |
| `template.components` | Opcional. Valores das variáveis, **no formato de envio da Meta**: o Messajo repassa como você escreveu |

Os campos comuns (`to`, `reply_to`, `typing`…) estão em [Campos comuns](/send/text/#campos-comuns). Template não depende da janela de 24 horas: sai a qualquer momento.

### Variáveis do corpo

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_enviado",
    "language": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          },
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "template",
  template: {
    name: "pedido_enviado",
    language: "pt_BR",
    components: [
      {
        type: "body",
        parameters: [
          {
            type: "text",
            text: "Ana"
          },
          {
            type: "text",
            text: "12345"
          }
        ]
      }
    ]
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_enviado",
    "language": "pt_BR",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          },
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

### Cabeçalho de imagem

Para um template com cabeçalho de imagem, passe a imagem por link público.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promo_da_semana",
    "language": "pt_BR",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://exemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          }
        ]
      }
    ]
  }
}'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "template",
  template: {
    name: "promo_da_semana",
    language: "pt_BR",
    components: [
      {
        type: "header",
        parameters: [
          {
            type: "image",
            image: {
              link: "https://exemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        type: "body",
        parameters: [
          {
            type: "text",
            text: "Ana"
          }
        ]
      }
    ]
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "promo_da_semana",
    "language": "pt_BR",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://exemplo.com/promo.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Ana"
          }
        ]
      }
    ]
  }
}
```

### Botão de URL com sufixo dinâmico

Quando a URL do botão termina em `{{1}}`, mande o sufixo em um componente `button` com `sub_type: "url"`. `index` é a posição do botão, a partir de `"0"`.

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "acompanhar_pedido",
    "language": "pt_BR",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  connection_id: "conn_...",
  to: "5511999999999",
  type: "template",
  template: {
    name: "acompanhar_pedido",
    language: "pt_BR",
    components: [
      {
        type: "button",
        sub_type: "url",
        index: "0",
        parameters: [
          {
            type: "text",
            text: "12345"
          }
        ]
      }
    ]
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "acompanhar_pedido",
    "language": "pt_BR",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "12345"
          }
        ]
      }
    ]
  }
}
```

A resposta é a mesma do envio de texto (`201`, `status: "queued"`); veja [Resposta](/send/text/#resposta).

## Custos

A Meta cobra por mensagem de template, conforme a categoria. Veja [Custos da Meta](/guides/costs/).

## Erros

| Erro | Quando | O que fazer |
| --- | --- | --- |
| `422` [`template_error`](/errors#template_error) | A Meta recusou o template ou os parâmetros (códigos 132000, 132001, 132005, 132007, 132012, 132015, 132016, 132068, 132069) | Leia `details[].message`: diz qual item falhou |
| `404` [`template_not_found`](/errors#template_not_found) | O template não existe | Confira `name` e `language`; rode `POST /v1/templates/sync` |
| `422` [`marketing_limit_reached`](/errors#marketing_limit_reached) | A Meta limitou marketing para esse contato (131049) | Não reenvie logo em seguida |
| `429` [`meta_spam_rate_limited`](/errors#meta_spam_rate_limited) | Limite por spam (131048) | Nunca reenvie |
| `402` [`meta_payment_required`](/errors#meta_payment_required) | Problema de pagamento na conta da Meta (131042) | Corrija a forma de pagamento |

Mais passos em [Falhas de envio](/troubleshooting/send-failures/).
