Modelos de Mensagem Reutilizáveis e Variáveis no Pilot Status

Modelos definem conteúdo de mensagem reutilizável. Crie e gerencie-os no painel (/templates), pela API REST (/v1/templates) ou pelo servidor MCP (templates_create / templates_update / templates_delete). Ao enviar, referencie o modelo pelo templateId em POST /v1/messages/send e passe um objeto variables com chaves correspondentes.

Página de Templates do Pilot Status — A página de Templates — gere com IA, envie para a Meta e veja status de aprovação e categoria por template.

Categorias

A categoria é definida no momento da criação e não pode ser alterada depois:

MARKETING — mensagens promocionais (as 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.

Aprovação da Meta vs. modelos locais

Números oficiais (Meta): ao salvar um modelo com um número Meta selecionado, o painel pergunta se você deseja enviá-lo para revisão da Meta agora ou mantê-lo como rascunho e enviá-lo mais tarde. Uma vez enviado, categoria, idioma e status de aprovação seguem as regras da Meta. Um modelo só pode ser enviado em um número Meta depois de ter uma versão aprovada.
Números não oficiais (Pilot Status web): os modelos são criados localmente e são imediatamente utilizáveis — não há etapa de aprovação.

Os modelos retornados por GET /v1/templates trazem um campo source (de onde o modelo veio), um campo metaStatus (status de revisão da Meta, por exemplo PENDING, APPROVED, REJECTED) e uma flag sendable indicando se ele pode ser usado para envios agora.

Estrutura do modelo

Editor de template do Pilot Status — O editor de template — nome, mídia, corpo com {{variáveis}}, botões, categoria (OTP/Utilidade/Marketing), idioma e geração por IA.

Apenas o body é obrigatório.

Componente	Obrigatório	O que é
Header	opcional	Texto (≤60 caracteres, ≤1 variável) ou um item de mídia (`IMAGE` JPG/PNG, `VIDEO` MP4, `DOCUMENT` PDF).
Body	obrigatório	Texto principal (≤1024 caracteres) com marcadores `{{variable}}`.
Footer	opcional	Texto estático ≤60 caracteres, sem variáveis.
Buttons	opcional	Até 10 botões: `QUICK_REPLY` (≤10), `URL` (≤2), `PHONE_NUMBER` (≤1, E.164 com código do país), `COPY_CODE` (≤1, alfanumérico ≤15 caracteres), `PAYMENT_REQUEST` (≤1, PIX).

Valores de header de mídia: via REST passe header.url (URL http(s) pública) ou header.base64 (data URI, re-hospedado automaticamente no servidor). Via MCP apenas header.url é aceito.

Não existe header LOCATION. Também não são suportados: FLOW, CAROUSEL, CATALOG/MPM, LIMITED_TIME_OFFER, preenchimento automático/one-tap/zero-tap de OTP e botões VOICE_CALL. O ORDER_DETAILS (card de pedido itemizado) pode ser montado, pré-visualizado e salvo; a submissão à Meta é tentada na versão atual da Graph API e, quando a conta ainda não está elegível ao WhatsApp Pay, a recusa volta como um erro claro de elegibilidade em vez de um 400 críptico da Meta.Em números não oficiais (web) os templates suportam até 3 botões no total, e o preview do editor mostra exatamente como a mensagem é entregue para o número selecionado — incluindo a substituição ao vivo das {{variáveis}} com seus valores de exemplo.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.

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Entrega um código PIX copia-e-cola (BR Code). É o jeito certo de mandar PIX — o COPY_CODE limita em 15 caracteres alfanuméricos, enquanto um BR Code real tem 100-400 caracteres com pontuação. O botão funciona nos dois tipos de número, com renderização diferente:

Números Meta (oficiais) — o card de pagamento do WhatsApp Pay (linha “Pagar com” + ícone do meio de pagamento), quando a conta tem pagamentos habilitados. Sem a habilitação, a Meta recusa o template com 100 / subcode 2388128 — a habilitação é gradual e por conta, e não há campo de API para consultar.
Números não oficiais (web) — entregue como um botão “Copiar código Pix” com o BR Code completo (sem limite de tamanho; validado em aparelhos reais). Ele combina normalmente com os demais botões do template, e o preview do editor mostra exatamente essa forma.

O código é um valor por envio: coloque uma variável no example do botão e passe o código real em variables na hora do envio, como qualquer outra variável.

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

A variável do código PIX é obrigatória no envio. Se faltar, o envio é recusado em vez de entregue: sem o parâmetro, a Meta usaria o código de amostra salvo no template, e o cliente pagaria a conta errada.

Card de pedido itemizado (`orderDetails`)

Um template pode carregar um card de pedido itemizado — PEDIDO #referência, itens com quantidade, a linha “Pagar com” e o total — gravado como um bloco orderDetails (order com itens/subtotal/impostos em centavos inteiros, mais paymentSettings com o meio de pagamento). Comportamento por tipo de número:

Meta (oficial) — o card é montado, pré-visualizado e salvo; a submissão à Meta é tentada na versão atual da Graph API e retorna um erro claro de elegibilidade quando a conta não tem WhatsApp Pay.
Não oficial EVO_V2 — o card é entregável hoje (review_and_pay). Quando o template também tem texto, botões ou mídia no header, eles são entregues primeiro como mensagem normal e o card de pedido vem numa segunda mensagem; se o card falhar depois da primeira mensagem entregue, o envio é marcado como falho (sem retry, pra não duplicar o texto).
Não oficial EVO_GO — não há card itemizado; quando o pedido tem trilho PIX, degrada para um botão “Copiar código Pix” anexado aos demais botões do template.

Variáveis no card de pedido: campos de texto (nome do item, referência, moeda) aceitam {{variáveis}} como qualquer outro campo. Campos numéricos — preço do item, quantidade, subtotal, impostos, total — também aceitam um único token {{variável}}: o exemplo precisa ser um inteiro não-negativo (em centavos), o valor real é substituído no envio, e um envio com valor numérico corrompido é recusado em vez de entregue com o valor errado.

Regras de variáveis

Escreva variáveis como {{name}} no body, no header de texto e em botões de URL dinâmica (por exemplo https://shop.com/promo/{{link}} — uma variável, no fim da URL, nunca no domínio).
O body não pode começar nem terminar com uma variável — sempre inclua texto literal em ambas as extremidades.
Ao criar/atualizar via API ou MCP, um objeto examples mapeando todas as variáveis a um valor de exemplo real é obrigatório. Amostras ausentes retornam 400 TEMPLATE_EXAMPLES_REQUIRED com as chaves faltantes em details.missing.
O valor do copy-code é a única exceção: ele vai no botão como example (por exemplo ["PROMO10"]), não em examples de nível superior.
Ao enviar, todo marcador — incluindo chaves usadas apenas em botões — deve ser fornecido em variables, e cada valor deve ser uma string não vazia.

Formatação de texto

Marcadores de formatação do WhatsApp funcionam no body: *bold*, _italic_, ~strikethrough~, monospace. O header de texto não permite marcadores de formatação, emojis nem quebras de linha.

API de Modelos

curl -X POST "https://pilotstatus.com.br/v1/templates" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_coupon",
    "category": "MARKETING",
    "language": "pt_BR",
    "body": {
      "header": { "type": "IMAGE", "url": "https://cdn.example.com/banner.png" },
      "body":   { "text": "Hi {{name}}! Use it and get {{discount}} off." },
      "footer": { "text": "Limited-time offer" },
      "buttons": [
        { "type": "QUICK_REPLY",  "text": "I want it!" },
        { "type": "URL",          "text": "Buy", "url": "https://shop.com/promo/{{link}}" },
        { "type": "COPY_CODE",    "example": ["PROMO10"] }
      ]
    },
    "examples": { "name": "Maria", "discount": "10%", "link": "abc123" }
  }'

curl -X PUT "https://pilotstatus.com.br/v1/templates/tmpl_123" \
  -H "x-api-key: ps_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "body": { "body": { "text": "Hi {{name}}! New copy here." } }, "examples": { "name": "Maria" } }'

curl -X DELETE "https://pilotstatus.com.br/v1/templates/tmpl_123" \
  -H "x-api-key: ps_your_key_here"

Uma criação bem-sucedida retorna 201:

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

Após salvar, GET /v1/templates/{id} retorna todas as chaves de variáveis detectadas no array variables de nível superior (plano).

Erros comuns de envio e submissão

Situação	Correção	Código Meta
Body começa/termina com uma variável	Adicione texto literal em ambas as extremidades	`2388299`
Botão de URL em um domínio de exemplo (example.com, yourdomain.com…)	Use o domínio real da sua empresa	`368/1346003`
Botão de chamada com telefone sem código do país	Use E.164, por exemplo `+5521999998888`	`192`
Variáveis demais em relação ao texto fixo	Adicione texto ou remova variáveis	`2388293`
Enviar um modelo ainda não aprovado pela Meta	Aguarde a aprovação	`131053`
Variáveis enviadas não correspondem ao modelo aprovado	Envie todas as chaves esperadas	`132000`
Modelo pausado pela Meta por queda de qualidade	Melhore o conteúdo, reduza as denúncias	`132015`

Um 404 ao enviar significa que o modelo não existe para a chave ou — em um número Meta — ainda não tem uma versão aprovada.

Primeiros Passos

Conceitos

Guias

Integrações

Painel

Confiança & Dados

Planos & Suporte

Changelog

Modelos de Mensagem Reutilizáveis e Variáveis no Pilot Status

Categorias

Aprovação da Meta vs. modelos locais

Estrutura do modelo

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Card de pedido itemizado (`orderDetails`)

Regras de variáveis

Formatação de texto

API de Modelos

Erros comuns de envio e submissão

Relacionados

​Categorias

​Aprovação da Meta vs. modelos locais

​Estrutura do modelo

​Botão de pagamento PIX (PAYMENT_REQUEST)

​Card de pedido itemizado (orderDetails)

​Regras de variáveis

​Formatação de texto

​API de Modelos

​Erros comuns de envio e submissão

​Relacionados

Categorias

Aprovação da Meta vs. modelos locais

Estrutura do modelo

Botão de pagamento PIX (`PAYMENT_REQUEST`)

Card de pedido itemizado (`orderDetails`)

Regras de variáveis

Formatação de texto

API de Modelos

Erros comuns de envio e submissão

Relacionados