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

# Modelos de mensagem pela API

> Crie, leia, edite e exclua modelos internos e modelos oficiais do WhatsApp Business, com variáveis {{n}} e as regras da Meta.

A API gerencia a mesma biblioteca de modelos do painel em [Modelos de mensagem](https://crmspark.com.br/dash/templates). Há dois tipos:

* Modelos oficiais: criados na conta do WhatsApp Business (WABA) do número escolhido e analisados pela Meta. Servem para iniciar conversas e para campanhas.
* Modelos internos: ficam só no Spark e não passam pela Meta.

Para entender os tipos de modelo e de variável no produto, veja [Modelos de mensagem](https://docs.crmspark.com.br/conceitos/modelos-de-mensagem.md).

Autenticação: chave secreta `sk_` no cabeçalho `X-API-Key`. URL base: [`https://gateway.crmspark.com.br`](https://gateway.crmspark.com.br). Veja a [Introdução à API](https://docs.crmspark.com.br/api-reference/introduction.md).

## Endpoints

| Método | Rota | Descrição |
| - | - | - |
| `POST` | `/v1/message-templates` | Cria um modelo oficial ou interno (`201`) |
| `GET` | `/v1/message-templates` | Lista os modelos |
| `GET` | `/v1/message-templates/{id}` | Detalhe do modelo |
| `PATCH` | `/v1/message-templates/{id}` | Edita rótulo ou conteúdo |
| `DELETE` | `/v1/message-templates/{id}` | Exclui do Spark e, se for oficial, da Meta (`204`) |

A lista traz, para cada modelo, status, categoria, idioma, nome na Meta e motivo de rejeição. O detalhe traz também `header`, `body`, `footer`, `buttons`, `variables`, `items` e `commonVariables`, a lista de variáveis manuais que você informa ao enviar o modelo ou iniciar uma campanha.

## Modelo oficial

Envie `isOfficial: true` e estes campos:

| Campo | Obrigatório | Regra |
| - | - | - |
| `name` | sim | Rótulo no Spark. Pode ser alterado depois sem reenviar o modelo à Meta |
| `whatsappEntrypointId` | sim | ID do canal de WhatsApp Business cuja conta recebe o modelo |
| `metaTemplateName` | sim | Nome na Meta: letras minúsculas, números e `_`, até 512 caracteres |
| `category` | sim | `MARKETING` ou `UTILITY` |
| `language` | sim | Código de idioma da Meta, por exemplo `pt_BR` |
| `body` | sim | Corpo, até 1.024 caracteres |
| `header` | não | Texto (até 60 caracteres) ou mídia |
| `footer` | não | Rodapé, até 60 caracteres |
| `buttons` | não | Até 10 botões `QUICK_REPLY`, `URL` ou `PHONE_NUMBER`, com texto de até 25 caracteres |
| `variables` | não | Definição de cada variável `{{n}}` usada no modelo |
| `description` | não | Descrição interna |

Nome na Meta, idioma e categoria não podem ser alterados depois da criação.

```json theme={null}
{
  "name": "promo_maio",
  "isOfficial": true,
  "whatsappEntrypointId": "wa_entrypoint_…",
  "metaTemplateName": "promo_maio",
  "category": "MARKETING",
  "language": "pt_BR",
  "header": { "format": "TEXT", "text": "Olá {{1}}," },
  "body": "Seu cupom é {{2}}.",
  "footer": "Equipe Loja Exemplo",
  "buttons": [
    { "type": "QUICK_REPLY", "text": "Quero saber mais" },
    { "type": "URL", "text": "Abrir", "url": "https://exemplo.com/p/{{2}}" }
  ],
  "variables": [
    {
      "index": 1,
      "title": "Nome",
      "example": "Maria",
      "kind": "lead",
      "source": "chat.name"
    },
    { "index": 2, "title": "Cupom", "example": "A123", "kind": "common" }
  ]
}
```

### Cabeçalho de mídia

Use `format` `IMAGE`, `VIDEO` ou `DOCUMENT` e o `mediaId` de um arquivo enviado antes por `POST /v1/messaging/media`. Esse arquivo vai para a Meta como exemplo e é o mesmo usado nos envios.

```json theme={null}
{ "format": "IMAGE", "mediaId": "media_…" }
```

### Variáveis

Numere as variáveis como `{{1}}`, `{{2}}`, … no modelo inteiro (cabeçalho, corpo e URL dos botões). O Spark converte para a numeração que a Meta espera em cada parte.

| Campo | Regra |
| - | - |
| `index` | Número da variável (`1` para `{{1}}`) |
| `title` | Nome exibido no Spark, até 120 caracteres |
| `example` | Exemplo enviado à Meta, até 15 caracteres |
| `kind` | `common` (manual: você informa o valor no envio) ou `lead` (automática: o Spark preenche com os dados do chat) |
| `source` | Obrigatório quando `kind` é `lead`. Veja a tabela abaixo |

Valores de `source`:

| `source` | Valor usado |
| - | - |
| `chat.name` | Nome do chat |
| `chat.contact` | Telefone ou identificador do contato do chat |
| `chat.birthday` | Data de nascimento do contato |
| `lead.name` | Nome do lead |
| `lead.contact` | Contato do lead |
| `lead.display_contact` | Contato do lead no formato de exibição |
| `custom_field:<chave>` | Valor de um [campo personalizado](https://docs.crmspark.com.br/conceitos/campos-personalizados.md) |

As variáveis `common` aparecem em `commonVariables` no detalhe do modelo, com as chaves `var1`, `var2`, … que você usa no envio e nas [campanhas](https://docs.crmspark.com.br/api-reference/campaigns.md#variáveis-do-modelo).

### Editar um modelo oficial

* O conteúdo (texto, botões e exemplos) só pode ser editado quando o status é `APPROVED` ou `REJECTED`. A resposta volta com status `PENDING` até a Meta concluir a análise.
* Nos demais status, inclusive `PENDING`, você pode mudar o rótulo e o título e o tipo das variáveis. Mudanças de texto, botão ou exemplo são recusadas com `MESSAGE_TEMPLATE_NOT_EDITABLE`.
* A Meta limita quantas vezes um modelo aprovado pode ser editado. Quando o limite é atingido, a API devolve `MESSAGE_TEMPLATE_META_ERROR` com a mensagem da Meta.
* Depois de excluir um modelo oficial, a Meta não permite criar outro com o mesmo nome por cerca de 30 dias.

## Modelo interno

Envie `isOfficial: false`, `name` e `items`. A Meta não é chamada.

Cada item tem `order` (posição, a partir de `0`), `type` (`text`, `image`, `audio`, `video` ou `document`) e `text` ou `mediaId`, conforme o tipo.

```json theme={null}
{
  "name": "Boas-vindas",
  "isOfficial": false,
  "items": [
    { "order": 0, "type": "text", "text": "Olá {{1}}" }
  ],
  "variables": [
    { "index": 1, "title": "Nome", "example": "Maria", "kind": "lead", "source": "chat.name" }
  ]
}
```

## Erros

| Código | HTTP | Quando ocorre |
| - | - | - |
| `MESSAGE_TEMPLATE_NOT_FOUND` | 404 | O ID não existe na organização |
| `MESSAGE_TEMPLATE_NOT_EDITABLE` | 422 | Edição de conteúdo de um modelo oficial fora dos status `APPROVED` e `REJECTED` |
| `MESSAGE_TEMPLATE_META_NAME_TAKEN` | 409 | Já existe um modelo oficial com o mesmo nome e idioma na conta do WhatsApp |
| `MESSAGE_TEMPLATE_META_ERROR` | 400 | A Meta recusou criar, editar ou excluir o modelo. `message` traz o motivo |
| `VALIDATION_ERROR` | 400 | O conteúdo não segue as regras do modelo, ou houve tentativa de mudar nome na Meta, idioma ou categoria |

Se já existir um modelo com o mesmo rótulo (`name`) na organização, a API responde `409` com a mensagem "Já existe um template com esse nome.".


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.