Templates

Endpoints para gerenciar templates de mensagem do WhatsApp Business. Templates sao obrigatorios para enviar mensagens fora da janela de 24 horas e precisam ser aprovados pela Meta antes do uso.

Autenticacao

Todas as requisicoes exigem o header:

Authorization: Bearer <API_KEY>

GET /templates

Lista todos os templates de uma instancia, sincronizados com a Meta.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia

Curl:

curl "http://localhost:8200/templates?instance_id=uuid-da-instancia" \
  -H "Authorization: Bearer <API_KEY>"

Resposta (200 OK):

{
  "templates": [
    {
      "id": "123456789",
      "name": "fgts_simulacao_pronta",
      "language": "pt_BR",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Simulacao FGTS Pronta!"
        },
        {
          "type": "BODY",
          "text": "Ola {{1}}, sua simulacao de antecipacao FGTS esta pronta. Valor disponivel: R$ {{2}}. Clique abaixo para contratar."
        },
        {
          "type": "FOOTER",
          "text": "MAZAM Financeira"
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "URL",
              "text": "Ver Simulacao",
              "url": "https://app.mazam.com.br/simulacao/{{1}}"
            }
          ]
        }
      ],
      "quality_score": {
        "score": "GREEN"
      }
    }
  ]
}

POST /templates

Cria um novo template e envia para aprovacao da Meta. O template ficara com status PENDING ate ser revisado.

Request Body:

{
  "instance_id": "uuid-da-instancia",
  "name": "fgts_simulacao_pronta",
  "category": "UTILITY",
  "language": "pt_BR",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Simulacao FGTS Pronta!"
    },
    {
      "type": "BODY",
      "text": "Ola {{1}}, sua simulacao de antecipacao FGTS esta pronta. Valor disponivel: R$ {{2}}.",
      "example": {
        "body_text": [["Joao", "5.000,00"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "MAZAM Financeira"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Ver Simulacao",
          "url": "https://app.mazam.com.br/simulacao/{{1}}",
          "example": ["abc123"]
        }
      ]
    }
  ]
}

Campo	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia
`name`	string	Sim	Nome do template (lowercase, underscores, sem espacos)
`category`	string	Sim	`MARKETING`, `UTILITY` ou `AUTHENTICATION`
`language`	string	Sim	Codigo do idioma (ex: `pt_BR`, `en_US`)
`components`	array	Sim	Array de componentes (HEADER, BODY, FOOTER, BUTTONS)

Curl:

curl -X POST http://localhost:8200/templates \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia",
    "name": "fgts_simulacao_pronta",
    "category": "UTILITY",
    "language": "pt_BR",
    "components": [
      {
        "type": "BODY",
        "text": "Ola {{1}}, sua simulacao esta pronta.",
        "example": {
          "body_text": [["Joao"]]
        }
      }
    ]
  }'

Resposta (201 Created):

{
  "id": "123456789",
  "name": "fgts_simulacao_pronta",
  "status": "PENDING",
  "category": "UTILITY"
}

Regras de nome: Apenas letras minusculas, numeros e underscores. Maximo 512 caracteres. Nao pode comecar com numero.

DELETE /templates/{name}

Deleta um template pelo nome. Remove de todas as linguas daquele template.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia

Curl:

curl -X DELETE "http://localhost:8200/templates/fgts_simulacao_pronta?instance_id=uuid-da-instancia" \
  -H "Authorization: Bearer <API_KEY>"

Resposta (200 OK):

{
  "success": true
}

Atencao: A delecao e irreversivel. Templates deletados precisam ser recriados e passar por nova aprovacao.

POST /templates/test

Envia um template aprovado para um numero de teste. Util para validar a formatacao antes de envios em massa.

Request Body:

{
  "instance_id": "uuid-da-instancia",
  "template_name": "fgts_simulacao_pronta",
  "language": "pt_BR",
  "to": "5511888887777",
  "components": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Joao" },
        { "type": "text", "text": "5.000,00" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [
        { "type": "text", "text": "abc123" }
      ]
    }
  ]
}

Campo	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia
`template_name`	string	Sim	Nome do template (deve estar APPROVED)
`language`	string	Sim	Idioma do template
`to`	string	Sim	Numero do destinatario (com DDI, sem +)
`components`	array	Nao	Parametros variaveis do template

Curl:

curl -X POST http://localhost:8200/templates/test \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia",
    "template_name": "fgts_simulacao_pronta",
    "language": "pt_BR",
    "to": "5511888887777",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Joao" },
          { "type": "text", "text": "5.000,00" }
        ]
      }
    ]
  }'

Resposta (200 OK):

{
  "messaging_product": "whatsapp",
  "contacts": [
    { "input": "5511888887777", "wa_id": "5511888887777" }
  ],
  "messages": [
    { "id": "wamid.HBgNNTUxMTk..." }
  ]
}

POST /templates/sync

Sincroniza os templates da Meta com o banco de dados local. Atualiza status, componentes e qualidade de todos os templates.

Request Body:

{
  "instance_id": "uuid-da-instancia"
}

Curl:

curl -X POST http://localhost:8200/templates/sync \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia"
  }'

Resposta (200 OK):

{
  "synced": 12,
  "created": 2,
  "updated": 8,
  "deleted": 1
}

Status de Templates

Status	Descricao
`APPROVED`	Aprovado e pronto para uso
`PENDING`	Aguardando revisao da Meta
`REJECTED`	Rejeitado (ver motivo em `rejection_reason`)
`PAUSED`	Pausado por baixa qualidade
`DISABLED`	Desabilitado por baixa qualidade persistente

Categorias e Precos

Categoria	Uso	Custo
`UTILITY`	Confirmacoes, alertas, atualizacoes	Gratis dentro da janela de 24h
`MARKETING`	Promocoes, ofertas, reengajamento	Sempre cobrado
`AUTHENTICATION`	OTP, codigos de verificacao	Cobrado fora da janela

Dica: Use UTILITY para templates de notificacao de simulacao e status de proposta. Dentro da janela de 24h, nao tem custo.

Este guia foi útil?

Última atualização: 7 de abril de 2026

Templates

On this page