Referência · modelos

Templates

Consulte aprovação, qualidade e campos de envio dos modelos vinculados ao seu número.

GET/public/v1/templates

cURL · listar templates do número

curl "https://api.patrociniotech.com/public/v1/templates?phone_number_id=SEU_NUMERO_ID" \
  -H "Authorization: Bearer SUA_CHAVE"

cURL · acompanhar todos os status

curl "https://api.patrociniotech.com/public/v1/templates?phone_number_id=SEU_NUMERO_ID&status=ALL" \
  -H "Authorization: Bearer SUA_CHAVE"

Parâmetro	Uso
phone_number_id	ID do número que fará o envio. Se omitido, a listagem usa a conta WhatsApp principal; informe-o quando houver mais de uma conta vinculada.
status	Padrão: APPROVED. Use ALL para incluir modelos em análise, rejeitados e pausados.

Antes de usar o modelo, confira sendable: true e api_supported: true. Aprovação na Meta e suporte desta API são verificações diferentes.

A consulta usa cache de até 90 segundos. Ela não é uma confirmação de entrega: o status pode mudar após a consulta e o envio continua sujeito às regras da Meta. Se a consulta falhar ou não puder trazer todas as páginas dentro do limite, retorna 503 templates_unavailable; uma falha não vira catálogo vazio.

Reaproveite o catálogo por conta e número, atualizando periodicamente ou após uma recusa relacionada ao modelo. Consultá-lo antes de cada mensagem consome a mesma cota de 600 requisições por minuto por chave usada pelos envios.

O histórico preserva até dez botões na ordem do modelo, incluindo ações e respostas rápidas. Isso não amplia as combinações aceitas no envio: confira api_supported, os índices e os parâmetros exigidos pelo catálogo. Se um modelo for editado depois, a recuperação de um novo envio usa o texto e os botões guardados no aceite. Histórico antigo sem essa cópia não é reconstruído com conteúdo atual.

Como ler o modelo (link para esta seção)

Para cadastrar um modelo pela integração, use a seção Criar template nesta página. O catálogo continua sendo a fonte para conferir a aprovação antes de enviar.

JSON · um item de data.templates

{
  "id": "123456789012345",
  "name": "entrega_pedido_documento",
  "language": "pt_BR",
  "category": "UTILITY",
  "status": "APPROVED",
  "sendable": true,
  "api_supported": true,
  "api_unsupported_reason": null,
  "quality_score": { "score": "UNKNOWN", "date": null, "reasons": [] },

33 linhas

A listagem retorna esses itens em data.templates. O exemplo mostra os campos usados para preparar o envio; a resposta também inclui rodapé e componentes originais da Meta.

Campo	Como interpretar
id	Identificador do modelo na Meta. Nome e idioma também identificam a versão usada no envio.
status	Situação informada pela Meta. PENDING está em análise; APPROVED indica aprovação.
sendable	true somente quando status é APPROVED. Não garante que esta API suporte todos os componentes nem que o envio será entregue.
api_supported	Indica se esta API sabe preencher o formato. Quando false, api_unsupported_reason explica a limitação.
quality_score	Objeto com score, date e reasons informados pela Meta, ou null quando indisponível. Qualidade não é aprovação.
rejected_reason	Motivo de rejeição fornecido pela Meta, ou null. A ausência de motivo não significa aprovação.
message_send_ttl_seconds	Prazo de entrega configurado no modelo, em segundos, quando informado pela Meta. Não é a validade de um código na sua aplicação.

Preencher as variáveis (link para esta seção)

Formato	Como preencher
NAMED	Associe cada nome de `body.variable_names` ao valor correspondente. O exemplo abaixo usa a ordem retornada.
POSITIONAL	Envie `variables` na ordem de `{{1}}`, `{{2}}` e seguintes. Omita `variable_names`.

JSON · trecho do envio com variáveis nomeadas

{
  "template": "entrega_pedido_documento",
  "language": "pt_BR",
  "variable_names": ["pedido", "valor"],
  "variables": ["8421", "R$ 495,75"]
}

Use a quantidade de body.variables_count. Uma variável repetida no texto recebe o mesmo valor; não envie um valor extra por repetição.

O texto fixo pode ter quebras de linha. Uma variável não pode conter quebras, tabulações ou mais de quatro espaços consecutivos. Para uma lista, use AD: A798R5 • B6: MBSERQ; o WhatsApp ajusta a quebra visual à largura da tela.

Campos exigidos pelo modelo (link para esta seção)

Quando a resposta informa	Preencha no envio
header.needs_media: true	O objeto `header_media`, com tipo compatível com o cabeçalho e link do arquivo.
header.needs_text: true	`header_text`
buttons[].needs_url_param: true	`button_url_param` e `button_url_index`, conforme `buttons[].index`.
buttons[].needs_coupon: true	`coupon_code` e `coupon_index`. Este é o botão de cupom, não de autenticação.
buttons[].needs_otp: true	`otp_code`; `otp_index` deve ser 0 ou omitido.
footer	Não é um parâmetro de envio. footer.text mostra o rodapé aprovado; quando não houver rodapé, footer será null.

Consulte todos os campos de POST /messages para limites de tamanho e exemplos completos.

Modelos com PDF e sem PDF (link para esta seção)

Um cabeçalho DOCUMENT exige o documento em cada envio. A amostra cadastrada na aprovação não é enviada automaticamente. Sem PDF, use um modelo aprovado sem esse cabeçalho.

JSON · campos do documento no envio

{
  "header_media": {
    "type": "document",
    "link": "https://arquivos.suaempresa.com/bilhetes/8421.pdf",
    "filename": "Bilhete 8421.pdf"
  }
}

Use uma URL HTTPS acessível pela Meta sem sessão de navegador e disponível durante o envio. Veja o exemplo completo com PDF.

Código de verificação e expiração (link para esta seção)

Para confirmar acesso ou uma ação, como saque, use AUTHENTICATION com botão OTP. No painel de Templates, o formato disponível é Copiar código.

WhatsApp · prévia ilustrativa

Seu código de verificação é *123456*.
Para sua segurança, não o compartilhe.

Expira em 10 minutos.

[Copiar código]

Controle	O que faz
Prazo no texto	Informa a validade do código ao destinatário. Não executa a validação da sua operação.
Validade no seu servidor	Impede usar o código vencido ou já utilizado. Associe-o à pessoa e à operação e limite as tentativas.
Prazo de entrega da Meta	Limita as tentativas de entregar a mensagem. Não apaga ou edita uma mensagem já recebida.

A Patrocinio Tech transporta o código. Seu sistema é responsável por gerar, expirar e validar o código antes de autorizar o saque ou outra ação. Não dependa da aparência do botão para decidir se o código ainda vale.

Veja como enviar o código pela API e a referência da Meta para templates com Copiar código.

E o preenchimento automático com um toque?

A Meta documenta a desativação do botão após o prazo no formato de preenchimento automático com um toque, que exige integração com aplicativo Android. Esse formato é diferente do botão Copiar código criado aqui.

Aprovação e mudanças de status (link para esta seção)

Status da Meta	Próximo passo
APPROVED	Confira api_supported e preencha os campos exigidos.
PENDING	Aguarde a análise da Meta.
REJECTED	Consulte o motivo da rejeição no painel de Templates.
PAUSED / DISABLED	Confira a qualidade, o motivo e as opções de reativação na Meta.
IN_APPEAL	Aguarde o resultado da contestação na Meta.
PENDING_DELETION / DELETED / ARCHIVED	Não use o modelo para novos envios.
LIMIT_EXCEEDED	Confira o limite indicado pela Meta antes de tentar novamente.

A categoria e a aprovação pertencem à Meta e podem mudar. Reconsulte a listagem se um modelo antes disponível passar a falhar.

O filtro status aceita esses códigos ou ALL, sem distinguir maiúsculas de minúsculas. Um filtro vazio ou desconhecido retorna 400 invalid_template_status.

Qualidade do modelo (link para esta seção)

quality_score.score	Significado
GREEN	Qualidade alta informada pela Meta.
YELLOW	Qualidade média; acompanhe o desempenho e o conteúdo.
RED	Qualidade baixa; revise conteúdo e público antes de ampliar os envios.
UNKNOWN / null	Sem avaliação disponível. Não trate como qualidade alta nem como rejeição.

quality_score.date é o horário Unix, em segundos, informado pela Meta para a avaliação, quando disponível. Não é o horário desta consulta. reasons preserva as informações de motivo que a Meta disponibilizar. Códigos futuros devem aparecer como desconhecidos na sua interface, sem interromper a leitura do catálogo.

Habilite template.status e template.quality em Integrações para receber as mudanças enviadas pela Meta. As assinaturas existentes são preservadas. Consulte também o catálogo com status=ALL: eventos podem chegar fora de ordem, e uma consulta reconcilia o estado atual.

Formatos disponíveis nesta API (link para esta seção)

api_supported: false vem acompanhado de api_unsupported_reason, uma explicação em português. A aprovação da Meta, indicada por sendable, não substitui essa verificação.

Recurso	Suporte
Texto, imagem, vídeo e documento	Disponíveis conforme o cabeçalho aprovado.
Link variável	Um botão de link dinâmico por template.
Autenticação	Um botão OTP, na posição 0, sem cabeçalho.
Cobrança PIX	Template de detalhes do pedido com um botão ORDER_DETAILS na posição 0.
Carrossel, oferta por tempo limitado, localização, GIF e Flow	Indisponíveis neste envio. A tentativa é recusada com template_format_unsupported.

O campo components permite inspecionar os dados originais da Meta; ele não amplia os formatos aceitos. Novidades como Direct Send dependem de suporte específico na API. Acompanhe as mudanças desta integração.

Criar template (link para esta seção)

POST/public/v1/templates

A chave da integração permite submeter modelos da própria empresa. Informe sempre o número que seleciona a conta WhatsApp. A validação é a mesma do painel; nome e idioma identificam o modelo na Meta. Criar não envia mensagens e não garante aprovação.

JSON · modelo de utilidade

{
  "phone_number_id": "SEU_NUMERO_ID",
  "name": "pedido_recebido",
  "language": "pt_BR",
  "category": "UTILITY",
  "body": "Recebemos seu pedido {{pedido}}. Aguarde nossa confirmação.",
  "body_examples": {
    "pedido": "DEMO-1"
  },
  "footer": "Acompanhe pelo nosso site.",

18 linhas

Campo	Regra
name / language / category	Nome com letras minúsculas, números e sublinhado, até 60 caracteres. Idioma como pt_BR. Categoria UTILITY, MARKETING ou AUTHENTICATION.
body / body_examples	Corpo até 1.024 caracteres. Variáveis numeradas consecutivas ou nomeadas, sem misturar; um exemplo fictício por variável.
header / footer	Texto fixo de até 60 caracteres cada. Sem variáveis. Não combine cabeçalho de texto com mídia.
header_format / header_handle	IMAGE, VIDEO ou DOCUMENT exigem o handle de amostra devolvido pelo upload abaixo. TEXT usa header.
buttons	Até 10, respeitando as combinações suportadas: QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE e ORDER_DETAILS. A criação não amplia o suporte do envio.
code_expiration_minutes	Autenticação: de 1 a 90 minutos, padrão 10. Corpo e botão Copiar código são definidos pela Meta; não envie body, footer ou buttons personalizados.
message_send_ttl_seconds	Prazo para entrega da mensagem. Na autenticação, 30 a 900 segundos, sem ultrapassar a validade do código; padrão até 600 segundos. Expire o código no seu backend também.

JSON · aceite da criação

{
  "success": true,
  "data": {
    "name": "pedido_recebido",
    "id": "123456789012345",
    "status": "PENDING",
    "category": "UTILITY"
  }
}

Em timeout ou 503 template_creation_unconfirmed, o resultado é incerto. Consulte o catálogo pelo mesmo nome e idioma antes de repetir. Não gere nomes novos automaticamente; name_taken pede conferir o modelo existente. Esta rota não usa a Idempotency-Key do envio de mensagens.

POST/public/v1/templates/header-sample

Envie multipart/form-data com phone_number_id e file. JPEG/PNG até 5 MB; MP4/3GPP/PDF até 16 MB. O tipo e a assinatura do arquivo são validados. A resposta contém data.handle e data.format; use-os na criação. O handle não é uma URL nem o media_id usado ao enviar mensagens. Use arquivos fictícios como amostra.

cURL · amostra de PDF

curl "https://api.patrociniotech.com/public/v1/templates/header-sample" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -F "phone_number_id=SEU_NUMERO_ID" \
  -F "file=@exemplo.pdf;type=application/pdf"