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 — só uma amostra em números oficiais)	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. No envio, ela é preenchida pelo nome (variables.link). Um template criado no painel da Meta com placeholder numerado (https://ctlnk.io/{{1}}) é preenchido por button_<N> — veja Placeholders de botão em templates criados na Meta.
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. Em um número oficial esse example é só uma amostra: o código que o cliente copia vai em variables como button_<N> a cada envio — veja Botões de copiar código em números oficiais.

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.

O ORDER_DETAILS (card de pedido itemizado) pode ser montado, pré-visualizado e salvo — veja Card de pedido itemizado.

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.

Placeholders de botão em templates criados na Meta

Um template criado no WhatsApp Manager da Meta e sincronizado no Pilot Status (source: "META") com placeholders posicionais numera a variável de um botão de URL dinâmica por conta própria: em https://ctlnk.io/{{1}}, esse {{1}} não é o {{1}} do body. Mande o valor dele como variables["button_<N>"], em que N é a posição do botão na lista de botões do template, começando em 1 — todos os botões contam, inclusive os estáticos. Passe só a parte variável (o sufixo da URL), não a URL inteira:

"variables": { "1": "Maria", "2": "R$ 10,00", "3": "21/09/2026", "button_1": "Gggkf" }

GET /v1/templates e GET /v1/templates/{id} listam a chave em variables — ["1", "2", "3", "button_1"] para o template acima.
Um envio sem ela, ou com valor vazio, é recusado com 400 MISSING_TEMPLATE_VARIABLES (ou INVALID_TEMPLATE_VARIABLE_VALUE) nomeando a chave, em vez de ser aceito e falhar depois com o 131008 da Meta.
Placeholders nomeados não mudam: um botão criado no Pilot Status como https://loja.com/promo/{{link}} é preenchido por variables.link.
A mesma chave button_<N> leva o código de um botão de copiar código num número oficial — veja abaixo.

Botões de copiar código em números oficiais

Para a Meta, o código digitado num botão COPY_CODE na criação é só um exemplo; o código que o cliente copia é um parâmetro obrigatório de todo envio. Por isso, num template aprovado pela Meta (source: "META" — todo template de um número oficial, criado no painel da Meta ou no Pilot Status), um botão de copiar código cujo valor não tem {{variável}} (um exemplo fixo como PROMO10) recebe o código como variables["button_<N>"], com a mesma regra: N é a posição do botão na lista de botões do template, começando em 1, e todos os botões contam. Para os botões [QUICK_REPLY, COPY_CODE] com o exemplo PROMO10:

"variables": { "button_2": "BLACKFRIDAY" }

GET /v1/templates e GET /v1/templates/{id} listam a chave em variables — button_4 para o template promo_cupom de Criar via API REST.
Um envio sem ela, ou com valor vazio, é recusado com 400 MISSING_TEMPLATE_VARIABLES (ou INVALID_TEMPLATE_VARIABLE_VALUE) nomeando a chave. O example mantém o limite da criação (15 caracteres alfanuméricos); para o código enviado, o limite da Meta é de 20 caracteres.
Um botão de copiar código cujo exemplo é uma variável nomeada (["{{cupom}}"]) continua sendo preenchido por variables.cupom. O botão de código de um template de autenticação (OTP) continua recebendo o código do body.
Números não oficiais (web/QR): o código também é gerado a cada envio — escreva-o no botão como {{variável}} (ex.: ["{{cupom}}"]) e preencha em variables.

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

LOCATION (header ou botão), CATALOG/MPM, LIMITED_TIME_OFFER, OTP autofill/one-tap/zero-tap e botões VOICE_CALL. (O carousel de sessão — a variante fora de template — está na referência de Enviar mensagem.) Botões FLOW são suportados em números Meta — veja Enviar um Flow. O ORDER_DETAILS (card de pedido itemizado) pode ser montado, pré-visualizado e salvo — veja Card de pedido itemizado para o comportamento por tipo de número. 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 — para placeholder numerado em botão de template criado no painel da Meta, como `button_<N>`	`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	— (a Pilot Status recusa antes de chamar a Meta: `META_TEMPLATE_NOT_APPROVED`)
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

Linhas Telefônicas

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)

Placeholders de botão em templates criados na Meta

Botões de copiar código em números oficiais

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)

​Placeholders de botão em templates criados na Meta

​Botões de copiar código em números oficiais

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

Placeholders de botão em templates criados na Meta

Botões de copiar código em números oficiais

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