API de Templates — Criar, Atualizar, Excluir

Templates definem conteúdo de mensagem reutilizável. Crie e gerencie-os no painel (/templates) ou via API REST pública (/v1/templates) e o servidor MCP (templates_create / templates_update / templates_delete). Ao enviar, referencie o template pelo templateId e passe um objeto variables com chaves correspondentes.

Modal de envio de template via API com curl pronto — Todo template tem uma chamada de API pronta — o modal "Enviar via API" do editor gera o curl exato com o templateId.

Todas as requisições usam o header x-api-key: ps_... (ou x-api-key-id). URL base: https://pilotstatus.com.br/v1.

Categoria

Definida no momento da criação; não pode ser alterada depois.

MARKETING — mensagens promocionais (mais sensíveis às políticas do WhatsApp).
UTILITY — mensagens transacionais (atualizações de conta, alertas, lembretes).
OTP — mensagens de código único / de verificação.

Estrutura do template

Apenas o body é obrigatório.

Componente	Obrigatório	O que é
Header	opcional	Texto ou um item de mídia (imagem, vídeo, PDF).
Body	obrigatório	Texto principal com placeholders `{{variable}}`.
Footer	opcional	Linha estática curta abaixo do body.
Buttons	opcional	Até 10 botões interativos.

Tipo	Valor	Observações
`NONE`	—	Padrão.
`TEXT`	`text`	Até 60 caracteres, 0 ou 1 variável. Sem quebras de linha/emojis/formatação.
`IMAGE`	`url` ou `base64`	JPG/PNG.
`VIDEO`	`url` ou `base64`	MP4.
`DOCUMENT`	`url` ou `base64`	PDF.

API REST: passe header.url (URL http(s) pública) ou header.base64 (data URI) — o base64 é re-hospedado no servidor automaticamente.
MCP: header.url apenas — base64 não é suportado via MCP.

Não existe header LOCATION.

Body

Até 1024 caracteres.
Variáveis escritas como {{nome}} (estilo nomeado).
O body não pode começar nem terminar com uma variável.
Emojis e múltiplas variáveis são permitidos.

Texto estático de até 60 caracteres. Sem variáveis.

Buttons

Até 10 botões no total; botões de resposta rápida e CTA podem ser combinados.

Tipo	Campos	Limite
`QUICK_REPLY`	`text`	até 10
`URL`	`text`, `url` (estática ou dinâmica)	até 2
`PHONE_NUMBER`	`text`, `phone_number` (E.164)	até 1
`COPY_CODE`	`example` (código a copiar)	até 1
`PAYMENT_REQUEST`	`text`, `paymentType`, `example` (código PIX)	até 1

Botão de URL dinâmica: a URL termina com uma variável (ex.: https://loja.com/promo/{{link}}) — no máximo uma variável, nunca no domínio. O valor de exemplo vai em examples.
Copy-code: o valor vai no botão como example (array, ex.: ["PROMO10"]), somente alfanumérico, até 15 caracteres. Não serve para chave PIX ou e-mail — para PIX use o botão PAYMENT_REQUEST abaixo.

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Botão de pagamento do WhatsApp Pay Brasil: o cliente toca e copia o código PIX. É o caminho certo para PIX copia-e-cola — o COPY_CODE trava em 15 caracteres alfanuméricos e um BR Code tem 100-400 caracteres com pontuação. O código é por envio: escreva uma variável no example do botão e mande o valor real em variables no envio, como qualquer outra variável.

{ "type": "PAYMENT_REQUEST", "text": "Copiar código Pix",
  "paymentType": "pix_dynamic_code", "example": ["{{codigo_pix}}"] }

Esse botão depende de a Meta ter liberado pagamentos para a sua WhatsApp Business Account. A liberação é gradual e por conta — a própria Meta diz “this feature is rolling out and might not be available yet for your WhatsApp Business account”. Numa conta sem liberação, a Meta recusa a criação do template com 100 / subcode 2388128 (“Button at index 0 has unexpected type (PAYMENT_REQUEST)”). Não há como consultar essa permissão pela API — só tentando criar.

Ao enviar, a variável do código PIX é obrigatória. Se ela faltar, o envio é recusado em vez de seguir: sem o parâmetro a Meta usaria o código de exemplo cadastrado no template, e o cliente pagaria para a conta errada.

ORDER_DETAILS — o botão de pagamento legado da Meta — não é suportado. Ele exige a API de Pedidos (order details) completa. Use PAYMENT_REQUEST.

Botões são permitidos junto com um header de vídeo ou documento (PDF).

Variáveis & examples (obrigatório)

Ao criar/atualizar via REST ou MCP você deve incluir um objeto examples mapeando cada variável usada (body + texto do header + URL dinâmica) para um valor de exemplo real. O valor do copy-code é a única exceção (ele fica no botão).

400 { "code": "TEMPLATE_EXAMPLES_REQUIRED", "details": { "missing": ["desconto"] } }

Após salvar, GET /v1/templates/{id} retorna todas as chaves detectadas no array variables de nível superior (um string[]) — forneça todas elas em variables no envio. Não há objeto latestVersion na resposta da API pública.

Limites de caracteres

Componente	Limite	Regras
Header (texto)	60	Sem quebras de linha/emojis/formatação; no máximo 1 variável.
Body	1024	Não pode começar nem terminar com uma variável.
Footer	60	Sem variáveis.
Rótulo do botão	25	—
Valor do copy-code	15	Somente alfanumérico.
Código PIX (`PAYMENT_REQUEST`)	2000	Aceita pontuação; um BR Code real tem 100-400.

Criar via API REST

curl -X POST https://pilotstatus.com.br/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
  "name": "promo_cupom",
  "category": "MARKETING",
  "language": "pt_BR",
  "body": {
    "header": { "type": "IMAGE", "url": "https://cdn.exemplo.com/banner.png" },
    "body":   { "text": "Oi {{nome}}! Use e ganhe {{desconto}} de desconto." },
    "footer": { "text": "Promoção por tempo limitado" },
    "buttons": [
      { "type": "QUICK_REPLY",  "text": "Quero!" },
      { "type": "URL",          "text": "Comprar", "url": "https://loja.com/promo/{{link}}" },
      { "type": "PHONE_NUMBER", "text": "Falar",   "phone_number": "+5511999998888" },
      { "type": "COPY_CODE",    "example": ["PROMO10"] }
    ]
  },
  "examples": { "nome": "Maria", "desconto": "10%", "link": "abc123" }
}'

{ "id": "tmpl_123", "name": "promo_cupom", "category": "MARKETING", "metaStatus": "PENDING" }

body pode ser um objeto (recomendado), uma string JSON ou texto simples (templates só de body).
Edite com PUT /v1/templates/{id} (mesmo formato); remova com DELETE /v1/templates/{id} — para um template Meta isso também pede à Meta para excluí-lo, e a resposta depende do que a Meta faz (veja Excluir).
GET /v1/templates / GET /v1/templates/{id} retornam source (META | PILOT_STATUS), metaStatus (APPROVED | PENDING | REJECTED | DISABLED | null), metaLanguage e sendable — em um número Meta apenas templates META com metaStatus: "APPROVED" são enviáveis.

Excluir

DELETE /v1/templates/{id} não retorna mais sucesso sempre. Para um template Meta a exclusão é encaminhada à Meta, e o resultado depende do que a Meta faz:

Resultado	HTTP	Corpo	Registro local
Removido dos dois lados	`200`	`{ "deleted": true, "id": "tmpl_123" }`	removido
A Meta recusou a exclusão	`409`	mensagem bilíngue nomeando o template e o motivo	mantido
Template realmente ausente na Meta (404 de verdade)	`200`	`{ "deleted": true, "id": "tmpl_123" }`	removido

Um 200 { "deleted": true, "id" } é a única resposta que significa que o template realmente sumiu — removido na Meta e localmente.
Um 409 significa que nada foi removido: a Meta rejeitou a exclusão (ex.: o system token não tem permissão na WABA), então o template ainda existe na Meta e o nome dele continua reservado. O registro local é mantido, e a mensagem nomeia o template e o motivo. Corrija a permissão e tente de novo.
Se a Meta informar que o template não existe (um 404 de verdade / “template does not exist”), o registro local obsoleto é removido e você ainda recebe 200 { "deleted": true, "id" }.

Templates de carrossel

Um template de carrossel é um template aprovado cujo body carrega um bloco carousel: uma faixa rolável na horizontal com 2 a 10 cartões de mídia, cada um com sua própria imagem, linha de texto e botões. Templates de carrossel são exclusivos de números Meta e sempre da categoria MARKETING — em um número Meta a criação é enviada à Meta como um componente CAROUSEL. Diferente do carrossel de sessão (interativo, somente resposta rápida — um botão de URL ali retorna 400), um cartão de carrossel de template pode combinar botões QUICK_REPLY e URL no mesmo cartão.

O bloco `carousel`

Ele fica dentro de body, ao lado de body.text — a mensagem exibida acima dos cartões (o corpo do carrossel).

Campo	O que é
`cardTemplate`	O esqueleto compartilhado que todo cartão deve seguir: uma decisão `hasBody` e uma lista `buttons` (tipos + ordem).
`cardTemplate.hasBody`	`true`/`false` — se todo cartão tem uma linha de texto. O body é tudo-ou-nada entre os cartões.
`cardTemplate.buttons`	Os tipos e a ordem dos botões que todo cartão repete, ex.: `[{ "type": "QUICK_REPLY" }, { "type": "URL" }]`.
`cards`	2 a 10 cartões. Cada cartão só preenche sua própria `media`, o texto de `body` e os valores dos botões (`text`, `payload`, `url`).

Limites (validados na criação e na atualização)

Os mesmos limites e regras de mídia valem para POST (criar) e PUT (atualizar) — a validação não é mais pulada.

Regra	Limite
Cartões	2 a 10
Botões por cartão	≤ 2
Body do cartão	≤ 160 caracteres
Body da mensagem (`body.text`, acima dos cartões)	≤ 1024 caracteres
Rótulo do botão (`text`)	≤ 20 caracteres
Payload / id do botão	≤ 256 caracteres
Body	tudo-ou-nada — ou todo cartão tem body, ou nenhum tem
Botões	todo cartão repete exatamente os tipos e a ordem de `cardTemplate.buttons`

Mídia do cartão — cada card.media.url deve ser uma URL https pública terminada em .png, .jpg, .jpeg ou .webp, sem query string. A Meta aceita uma imagem inacessível com 200 e depois não entrega nada, então a URL é buscada e recusada antes do envio, com um erro tipado que nomeia o cartão problemático.

Um header de nível superior não é permitido com carousel (a mídia fica em cada cartão), e os botões dos cartões substituem os buttons de nível superior.

Criar um template de carrossel

curl -X POST https://pilotstatus.com.br/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
  "name": "lancamentos_carrossel",
  "category": "MARKETING",
  "language": "pt_BR",
  "body": {
    "body": { "text": "Confira nossos lançamentos da semana!" },
    "carousel": {
      "cardTemplate": {
        "hasBody": true,
        "buttons": [{ "type": "QUICK_REPLY" }, { "type": "URL" }]
      },
      "cards": [
        {
          "media": { "format": "IMAGE", "url": "https://cdn.exemplo.com/tenis.png" },
          "body": "Tênis Runner — R$ 299",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Quero", "payload": "SKU-1" },
            { "type": "URL",         "text": "Ver produto", "url": "https://loja.com/p/tenis" }
          ]
        },
        {
          "media": { "format": "IMAGE", "url": "https://cdn.exemplo.com/jaqueta.png" },
          "body": "Jaqueta Wind — R$ 459",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "Quero", "payload": "SKU-2" },
            { "type": "URL",         "text": "Ver produto", "url": "https://loja.com/p/jaqueta" }
          ]
        }
      ]
    }
  }
}'

{ "id": "tmpl_car_1", "name": "lancamentos_carrossel", "category": "MARKETING", "metaStatus": "PENDING" }

Aqui todo cartão repete o par QUICK_REPLY + URL declarado em cardTemplate.buttons, nessa ordem. Um cartão que omite um botão, troca a ordem ou muda um tipo é recusado antes do envio.

Aprovação

Números Meta: os templates são enviados à Meta para revisão (“Submit to Meta” em /templates, ou ao salvar). Categorias, idioma e status seguem as regras da Meta.
Números não oficiais (Pilot Status web): os templates são criados localmente e ficam imediatamente utilizáveis — sem etapa de aprovação.

Não suportado

FLOW, LOCATION (header ou botão), CATALOG/MPM, LIMITED_TIME_OFFER, OTP autofill/one-tap/zero-tap, botões VOICE_CALL e ORDER_DETAILS (botão de pagamento legado — use PAYMENT_REQUEST). (O carousel de sessão — a variante fora de template — está na referência de Enviar mensagem.) O parameter_format NAMED é suportado: um template criado no painel da Meta com variáveis nomeadas ({{nome_do_cliente}}) é importado com as variáveis certas e enviado com parameter_name em cada parâmetro.

Erros de envio & rejeição

Botões de link/URL aceitam uma única variável que deve estar no final da URL e nunca no domínio; botões de chamada precisam do código do país (ex.: +55).

Verificado antes de enviar à Meta

Causa	Correção	Código Meta
Body começa/termina com uma variável	Adicione texto literal nas extremidades	`2388299`
Combinação de botões acima dos limites	≤10 no total, ≤10 quick-reply, ≤2 URL, ≤1 chamada, ≤1 copy-code	`100`
Botão de chamada sem código do país	Use E.164 (`+55 21 99999-8888`)	`192`
Botão de link em domínio placeholder (example.com…)	Use a URL real do seu negócio	`368/1346003`
Variável no domínio da URL	Variável apenas no final do path	`100`
Mais de uma variável na URL / não no final	Uma variável, no final	`100`
Copy-code com símbolos/espaços ou >15 caracteres	Alfanumérico ≤15	`100`
Footer contém uma variável	Remova-a	`2388073`
Header de texto com emoji/quebra de linha/formatação/2+ variáveis	Texto simples, ≤1 variável	`2388047`
Campo acima do limite de caracteres	Header 60, body 1024, footer 60, botão 25	`2388040`

Validação do lado da API

Causa	Correção	Código Meta
Variáveis demais em relação ao texto fixo	Adicione texto ou reduza as variáveis	`2388293`

A Meta rejeitou o envio

Causa	Correção	Código Meta
Header de mídia mas número sem Meta App ID	Defina o App ID nas configurações do número	—
Parâmetro inválido (motivo da Meta exibido)	Revise o campo indicado	`100`
Conteúdo marcado como abusivo (geralmente o domínio da URL do botão)	Revise os links dos botões	`368/1346003`
Nome de exibição ainda não aprovado	Aguarde a aprovação da Meta	`131037`
Parâmetro obrigatório ausente (ex.: variável de botão não preenchida)	Preencha todas as variáveis do template	`131008`
Botão de pagamento não liberado para esta WABA	Aguarde a liberação de pagamentos pela Meta	`100/subcode 2388128`
Link/variável de botão URL inválidos	Verifique o link e `{{…}}`	`100`
Falha no upload de mídia para a Meta	Arquivo do header acessível + formato válido	—
Arquivo do header muito grande / não suportado	Imagem ≤5MB JPEG/PNG, vídeo ≤16MB MP4, PDF ≤10MB	`131002/131003`
Número temporariamente bloqueado (política)	Resolva com a Meta	`368`
Token sem permissões do WhatsApp	Reconecte o número concedendo as permissões	`10/200/3`
Token inválido/expirado	Atualize o System Token	`190`
WABA inacessível/removida	Reconecte o número na Meta	`100/subcode 33`

Rejeitado após revisão

Motivo	Código Meta
Conteúdo ameaçador/abusivo/que viola políticas	`ABUSIVE_CONTENT`
Categoria não corresponde ao conteúdo	`INCORRECT_CATEGORY`
Formatação: variáveis ruins/adjacentes, examples ausentes	`INVALID_FORMAT`
Template de utilidade com conteúdo promocional	—
Parece um golpe (genérico, urgência falsa)	`SCAM`
Idioma selecionado ≠ texto escrito	—

Bloqueios ao enviar (mesmo aprovado)

Causa	Código Meta
Verificação de negócio não concluída	`141010`
Sem método de pagamento / fatura pendente na WABA	`131042 / 141006`
Template permanentemente desativado após pausas repetidas	`132016`
Template ainda não aprovado	`131053`
Contagem de variáveis ≠ template aprovado	`132000`
Template pausado por queda de qualidade	`132015`

Erro comum ao enviar

404 — template sem uma versão aprovada (não existe para a chave, ou o template Meta ainda não tem versão aprovada).

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

API de Templates — Criar, Atualizar, Excluir

Categoria

Estrutura do template

Header

Body

Footer

Buttons

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Variáveis & examples (obrigatório)

Limites de caracteres

Criar via API REST

Excluir

Templates de carrossel

O bloco `carousel`

Limites (validados na criação e na atualização)

Criar um template de carrossel

Aprovação

Não suportado

Erros de envio & rejeição

Verificado antes de enviar à Meta

Validação do lado da API

A Meta rejeitou o envio

Rejeitado após revisão

Bloqueios ao enviar (mesmo aprovado)

Erro comum ao enviar

​Categoria

​Estrutura do template

​Header

​Body

​Footer

​Buttons

​Botão de pagamento PIX (PAYMENT_REQUEST)

​Variáveis & examples (obrigatório)

​Limites de caracteres

​Criar via API REST

​Excluir

​Templates de carrossel

​O bloco carousel

​Limites (validados na criação e na atualização)

​Criar um template de carrossel

​Aprovação

​Não suportado

​Erros de envio & rejeição

​Verificado antes de enviar à Meta

​Validação do lado da API

​A Meta rejeitou o envio

​Rejeitado após revisão

​Bloqueios ao enviar (mesmo aprovado)

​Erro comum ao enviar

Categoria

Estrutura do template

Header

Body

Footer

Buttons

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Variáveis & examples (obrigatório)

Limites de caracteres

Criar via API REST

Excluir

Templates de carrossel

O bloco `carousel`

Limites (validados na criação e na atualização)

Criar um template de carrossel

Aprovação

Não suportado

Erros de envio & rejeição

Verificado antes de enviar à Meta

Validação do lado da API

A Meta rejeitou o envio

Rejeitado após revisão

Bloqueios ao enviar (mesmo aprovado)

Erro comum ao enviar