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.

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

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.

Aprovações e avisos de qualidade aparecem em Notificações do painel. O webhook público atual oferece message.status e message.received; ele não publica mudanças de templates. Para acompanhar modelos na integração, consulte este catálogo com status=ALL.

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.