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: 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.

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.

Payload

{
  "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

string

required

Deve ser "TEMPLATE".

Address

required

Endereço do destinatário. Veja formatos de endereço.

uuid

required

Id do template pré-aprovado que será enviado.

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.

Além dos campos acima, a mensagem aceita os campos comuns de envio: quotedMessage, deliveryStrategy, priority e deliveryDeadline. Veja Campos Comuns.

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. 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.

{
  "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.

{
  "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.

{
  "type": "button",
  "sub_type": "quick_reply",
  "index": 0,
  "parameters": [
    { "type": "payload", "payload": "CONFIRMAR_PEDIDO" }
  ]
}

{
  "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).

{
  "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.

string

required

Tipo do parâmetro. Valores: "text", "currency", "date_time", "image", "video", "document", "location", "payload", "coupon_code".

`text`

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

string

Valor de texto que preenche a variável.

string

Nome da variável, quando o template usa variáveis nomeadas ({{nome}}) em vez de posicionais. Omita no caso posicional.

{ "type": "text", "text": "Ryan" }

{ "type": "text", "text": "Ryan", "parameter_name": "nome_cliente" }

`currency`

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

string

Texto exibido quando o locale do destinatário não é suportado.

string

Código ISO 4217 da moeda (ex.: "BRL", "USD").

integer

Valor multiplicado por 1000 — R$ 12,34 vai como 12340. Evita ponto flutuante.

{
  "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.

string

Texto de data/hora exibido ao destinatário.

{
  "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).

string

URL pública do arquivo. O provedor baixa o conteúdo deste endereço.

string

Id de mídia já carregada no provedor. Alternativa a link.

string

Nome exibido do arquivo. Usado apenas em document.

{
  "type": "image",
  "image": { "link": "https://exemplo.com/produto.jpg" }
}

{
  "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.

string

Latitude como string (ex.: "-23.5505").

string

Longitude como string (ex.: "-46.6333").

string

Nome do local.

string

Endereço do local.

{
  "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.

string

Valor retornado no webhook de clique do botão.

{ "type": "payload", "payload": "CONFIRMAR_PEDIDO_12345" }

`coupon_code`

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

string

Código que será copiado pelo cliente ao tocar no botão.

{ "type": "coupon_code", "coupon_code": "PROMO20OFF" }

Exemplos

Template com variáveis no corpo

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
              }
            }
          ]
        }
      ]
    }
  }'

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())

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);

Template com cabeçalho de mídia

{
  "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

{
  "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:

{
  "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

{
  "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
  }
}

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

Resposta

{
  "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).

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.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Mensagem de Template

Mensagem de Template

Payload

Campos

Componentes (`components`)

`header` — Cabeçalho

`body` — Corpo

`button` — Botão

`carousel` — Carrossel

Parâmetros (`parameters`)

`text`

`currency`

`date_time`

`image`, `video`, `document`

`location`

`payload`

`coupon_code`

Exemplos

Template com variáveis no corpo

Template com cabeçalho de mídia

Template com botão

Template sem variáveis

Com prioridade e estratégia de entrega

Resposta

​Mensagem de Template

​Payload

​Campos

​Componentes (components)

​header — Cabeçalho

​body — Corpo

​button — Botão

​carousel — Carrossel

​Parâmetros (parameters)

​text

​currency

​date_time

​image, video, document

​location

​payload

​coupon_code

​Exemplos

​Template com variáveis no corpo

​Template com cabeçalho de mídia

​Template com botão

​Template sem variáveis

​Com prioridade e estratégia de entrega

​Resposta

Mensagem de Template

Payload

Campos

Componentes (`components`)

`header` — Cabeçalho

`body` — Corpo

`button` — Botão

`carousel` — Carrossel

Parâmetros (`parameters`)

`text`

`currency`

`date_time`

`image`, `video`, `document`

`location`

`payload`

`coupon_code`

Exemplos

Template com variáveis no corpo

Template com cabeçalho de mídia

Template com botão

Template sem variáveis

Com prioridade e estratégia de entrega

Resposta