Modelos de mensagem pela API

A API gerencia a mesma biblioteca de modelos do painel em Modelos de mensagem. 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. Autenticação: chave secreta sk_ no cabeçalho X-API-Key. URL base: https://gateway.crmspark.com.br. Veja a Introdução à API.

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.

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

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

As variáveis common aparecem em commonVariables no detalhe do modelo, com as chaves var1, var2, … que você usa no envio e nas campanhas.

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.

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

Documentação

Entrypoints

Forms

Chats

Campaigns

Message Templates

Messaging

Endpoints

Modelo oficial

Cabeçalho de mídia

Variáveis

Editar um modelo oficial

Modelo interno

Erros

​Endpoints

​Modelo oficial

​Cabeçalho de mídia

​Variáveis

​Editar um modelo oficial

​Modelo interno

​Erros

Endpoints

Modelo oficial

Cabeçalho de mídia

Variáveis

Editar um modelo oficial

Modelo interno

Erros