> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mensagem de Template

> Envie mensagens baseadas em templates pré-aprovados do WhatsApp Business

# Mensagem de Template

O tipo `TEMPLATE` envia uma mensagem baseada em um **template pré-aprovado** do WhatsApp Business, referenciado por id. É útil para notificações transacionais e mensagens iniciadas pela empresa fora da janela de atendimento de 24 horas, cenários em que o WhatsApp só permite conteúdo aprovado.

O envio funciona como uma [Mensagem de Texto](/mensagens/texto): o destinatário vai em `to` e o template é identificado por `templateId`. Quando o template possui variáveis ou componentes estruturados (cabeçalho, corpo, botões, carrossel), os valores são informados em `components`.

<Note>
  Esta página trata apenas do **envio** de uma mensagem de template. Para criar, listar e
  acompanhar a aprovação de templates, veja
  [Gerenciar Templates](/whatsapp-oficial/templates).
</Note>

## Payload

```json theme={null}
{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "TEMPLATE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Ryan" },
          { "type": "text", "text": "12345" }
        ]
      }
    ]
  }
}
```

## Campos

<ParamField body="content.type" type="string" required>
  Deve ser `"TEMPLATE"`.
</ParamField>

<ParamField body="content.to" type="Address" required>
  Endereço do destinatário. Veja [formatos de endereço](/mensagens/visao-geral#enderecamento-address).
</ParamField>

<ParamField body="content.templateId" type="uuid" required>
  Id do template pré-aprovado que será enviado.
</ParamField>

<ParamField body="content.components" type="object[]">
  Lista de componentes do template que serão preenchidos com os valores das variáveis. Cada componente possui um `type` que indica a seção do template (`header`, `body`, `button` ou `carousel`) e uma lista `parameters` com os valores que preenchem as variáveis daquela seção. Obrigatório apenas quando o template exigir variáveis ou componentes estruturados; omita quando o template não tiver nenhum.
</ParamField>

<Note>
  Além dos campos acima, a mensagem aceita os campos comuns de envio: `quotedMessage`, `deliveryStrategy`, `priority` e `deliveryDeadline`. Veja [Campos Comuns](/mensagens/visao-geral#campos-comuns).
</Note>

## Componentes (`components`)

Cada item de `components` é um objeto com `type` discriminando a seção do template. Os valores de `type` são em **minúsculas**.

### `header` — Cabeçalho

Preenche o cabeçalho do template. Aceita um único parâmetro, compatível com o formato declarado no template: texto para `HEADER TEXT`, ou mídia (`image`, `video`, `document`) para cabeçalho de mídia.

```json theme={null}
{
  "type": "header",
  "parameters": [
    {
      "type": "image",
      "image": { "link": "https://exemplo.com/produto.jpg" }
    }
  ]
}
```

### `body` — Corpo

Preenche as variáveis do corpo do template. Os parâmetros vão na **mesma ordem** das variáveis (`{"{{1}}"}'`, `{{2}}`, ...) definidas no corpo do template. Quando o template usa variáveis **nomeadas** (`{{nome}}`), cada parâmetro identifica a sua em `parameter_name`.

```json theme={null}
{
  "type": "body",
  "parameters": [
    { "type": "text", "text": "Ryan" },
    { "type": "text", "text": "12345" },
    {
      "type": "currency",
      "currency": {
        "fallback_value": "R$ 199,90",
        "code": "BRL",
        "amount_1000": 199900
      }
    }
  ]
}
```

### `button` — Botão

Preenche um botão específico do template. É necessário **um componente por botão**, identificado pela posição em `index` (começando em 0, na ordem em que foram declarados no template). O campo `sub_type` indica o tipo do botão: `quick_reply`, `url`, `copy_code` ou `flow`.

```json theme={null}
{
  "type": "button",
  "sub_type": "quick_reply",
  "index": 0,
  "parameters": [
    { "type": "payload", "payload": "CONFIRMAR_PEDIDO" }
  ]
}
```

```json theme={null}
{
  "type": "button",
  "sub_type": "url",
  "index": 1,
  "parameters": [
    { "type": "text", "text": "pedido-12345" }
  ]
}
```

### `carousel` — Carrossel

Preenche os cartões de um template carrossel. Cada cartão é identificado por `card_index` e possui sua própria lista de `components` (seguindo a mesma estrutura: `header`, `body`, `button`).

```json theme={null}
{
  "type": "carousel",
  "cards": [
    {
      "card_index": 0,
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "image",
              "image": { "link": "https://exemplo.com/produto1.jpg" }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Camiseta Azul" },
            { "type": "text", "text": "R$ 79,90" }
          ]
        }
      ]
    }
  ]
}
```

## Parâmetros (`parameters`)

Cada item de `parameters` tem um `type` que determina o tipo de valor enviado. Os valores de `type` são em **minúsculas**.

<ParamField body="parameters[].type" type="string" required>
  Tipo do parâmetro. Valores: `"text"`, `"currency"`, `"date_time"`, `"image"`, `"video"`, `"document"`, `"location"`, `"payload"`, `"coupon_code"`.
</ParamField>

### `text`

Valor de texto — o caso mais comum, usado no cabeçalho TEXT e no corpo.

<ParamField body="text" type="string">
  Valor de texto que preenche a variável.
</ParamField>

<ParamField body="parameter_name" type="string">
  Nome da variável, quando o template usa variáveis nomeadas (`{{nome}}`) em vez de posicionais. Omita no caso posicional.
</ParamField>

```json theme={null}
{ "type": "text", "text": "Ryan" }
```

```json theme={null}
{ "type": "text", "text": "Ryan", "parameter_name": "nome_cliente" }
```

### `currency`

Valor monetário. O provedor formata o valor conforme o locale de quem recebe.

<ParamField body="currency.fallback_value" type="string">
  Texto exibido quando o locale do destinatário não é suportado.
</ParamField>

<ParamField body="currency.code" type="string">
  Código ISO 4217 da moeda (ex.: `"BRL"`, `"USD"`).
</ParamField>

<ParamField body="currency.amount_1000" type="integer">
  Valor multiplicado por 1000 — R\$ 12,34 vai como `12340`. Evita ponto flutuante.
</ParamField>

```json theme={null}
{
  "type": "currency",
  "currency": {
    "fallback_value": "R$ 199,90",
    "code": "BRL",
    "amount_1000": 199900
  }
}
```

### `date_time`

Data/hora. O provedor exibe o valor de fallback informado.

<ParamField body="date_time.fallback_value" type="string">
  Texto de data/hora exibido ao destinatário.
</ParamField>

```json theme={null}
{
  "type": "date_time",
  "date_time": { "fallback_value": "15 de setembro de 2026" }
}
```

### `image`, `video`, `document`

Mídia para cabeçalho. Informe `link` (URL pública) ou `id` (id de mídia já carregada).

<ParamField body="{type}.link" type="string">
  URL pública do arquivo. O provedor baixa o conteúdo deste endereço.
</ParamField>

<ParamField body="{type}.id" type="string">
  Id de mídia já carregada no provedor. Alternativa a `link`.
</ParamField>

<ParamField body="{type}.filename" type="string">
  Nome exibido do arquivo. Usado apenas em `document`.
</ParamField>

```json theme={null}
{
  "type": "image",
  "image": { "link": "https://exemplo.com/produto.jpg" }
}
```

```json theme={null}
{
  "type": "document",
  "document": {
    "link": "https://exemplo.com/contrato.pdf",
    "filename": "contrato.pdf"
  }
}
```

### `location`

Localização para cabeçalho do tipo LOCATION. Latitude e longitude vão como **string**.

<ParamField body="location.latitude" type="string">
  Latitude como string (ex.: `"-23.5505"`).
</ParamField>

<ParamField body="location.longitude" type="string">
  Longitude como string (ex.: `"-46.6333"`).
</ParamField>

<ParamField body="location.name" type="string">
  Nome do local.
</ParamField>

<ParamField body="location.address" type="string">
  Endereço do local.
</ParamField>

```json theme={null}
{
  "type": "location",
  "location": {
    "latitude": "-23.5505",
    "longitude": "-46.6333",
    "name": "Loja Centro",
    "address": "Av. Paulista, 1000 - São Paulo"
  }
}
```

### `payload`

Payload do botão `quick_reply` — o valor é devolvido no webhook quando o cliente clica no botão.

<ParamField body="payload" type="string">
  Valor retornado no webhook de clique do botão.
</ParamField>

```json theme={null}
{ "type": "payload", "payload": "CONFIRMAR_PEDIDO_12345" }
```

### `coupon_code`

Código do botão `copy_code` — o código que o cliente copia.

<ParamField body="coupon_code" type="string">
  Código que será copiado pelo cliente ao tocar no botão.
</ParamField>

```json theme={null}
{ "type": "coupon_code", "coupon_code": "PROMO20OFF" }
```

## Exemplos

### Template com variáveis no corpo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
    -H "Content-Type: application/json" \
    -H "X-API-KEY: sua-api-key-aqui" \
    -d '{
      "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "content": {
        "type": "TEMPLATE",
        "to": {
          "type": "WHATSAPP",
          "number": "5511999999999"
        },
        "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
        "components": [
          {
            "type": "body",
            "parameters": [
              { "type": "text", "text": "Ryan" },
              { "type": "text", "text": "12345" },
              {
                "type": "currency",
                "currency": {
                  "fallback_value": "R$ 199,90",
                  "code": "BRL",
                  "amount_1000": 199900
                }
              }
            ]
          }
        ]
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-dev.messagefy.io/api/v1/message/SendMessage",
      headers={
          "Content-Type": "application/json",
          "X-API-KEY": "sua-api-key-aqui"
      },
      json={
          "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "content": {
              "type": "TEMPLATE",
              "to": {
                  "type": "WHATSAPP",
                  "number": "5511999999999"
              },
              "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
              "components": [
                  {
                      "type": "body",
                      "parameters": [
                          {"type": "text", "text": "Ryan"},
                          {"type": "text", "text": "12345"},
                          {
                              "type": "currency",
                              "currency": {
                                  "fallback_value": "R$ 199,90",
                                  "code": "BRL",
                                  "amount_1000": 199900
                              }
                          }
                      ]
                  }
              ]
          }
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api-dev.messagefy.io/api/v1/message/SendMessage",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key-aqui",
      },
      body: JSON.stringify({
        channelId: "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        content: {
          type: "TEMPLATE",
          to: {
            type: "WHATSAPP",
            number: "5511999999999",
          },
          templateId: "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
          components: [
            {
              type: "body",
              parameters: [
                { type: "text", text: "Ryan" },
                { type: "text", text: "12345" },
                {
                  type: "currency",
                  currency: {
                    fallback_value: "R$ 199,90",
                    code: "BRL",
                    amount_1000: 199900,
                  },
                },
              ],
            },
          ],
        },
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

### Template com cabeçalho de mídia

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "TEMPLATE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": { "link": "https://exemplo.com/produto.jpg" }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Camiseta Azul" },
          { "type": "text", "text": "R$ 79,90" }
        ]
      }
    ]
  }
}
```

### Template com botão

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "TEMPLATE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Ryan" }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [
          { "type": "payload", "payload": "CONFIRMAR" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 1,
        "parameters": [
          { "type": "text", "text": "pedido-12345" }
        ]
      }
    ]
  }
}
```

### Template sem variáveis

Quando o template não possui variáveis nem componentes estruturados, omita o campo `components`:

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": {
    "type": "TEMPLATE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b"
  }
}
```

### Com prioridade e estratégia de entrega

```json theme={null}
{
  "channelId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "correlationId": "confirmacao-pedido-8471",
  "content": {
    "type": "TEMPLATE",
    "to": {
      "type": "WHATSAPP",
      "number": "5511999999999"
    },
    "templateId": "b7e2c1a4-3f56-4d89-9a0b-1c2d3e4f5a6b",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Ryan" },
          { "type": "text", "text": "8471" }
        ]
      }
    ],
    "deliveryStrategy": 10,
    "priority": 1
  }
}
```

<Tip>
  Use `correlationId` para correlacionar o envio com o seu próprio identificador de rastreamento. Ele é retornado nos webhooks de status da mensagem.
</Tip>

## Resposta

```json theme={null}
{
  "packageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

O `packageId` identifica o pacote aceito para envio. Acompanhe a entrega pelos webhooks de status (`MESSAGE_SENT`, `MESSAGE_DELIVERED`, `MESSAGE_READ`).

<Warning>
  Os componentes e parâmetros enviados devem corresponder exatamente à estrutura definida no template aprovado. Componentes fora de ordem, com `type` incompatível ou em número diferente do esperado podem fazer o provedor rejeitar o envio.
</Warning>