Templates

Templates são o único formato que o WhatsApp entrega fora da janela de 24 horas. Todo template precisa ser aprovado pela Meta antes de ser enviado. Pela API você cobre o ciclo inteiro: criar, acompanhar a aprovação, editar e excluir.

Crie o template

POST /v1/whatsapp/templates com nome, idioma, categoria e componentes. Normalmente o template nasce com status: "PENDING" — a resposta traz o status lido na Meta.

Aguarde a aprovação

A análise da Meta leva de minutos a 24 horas. Assine o webhook whatsapp.template.updated ou consulte GET /v1/whatsapp/templates/{id}.

Envie

Com status: "APPROVED", use o name e o language do template em POST /v1/whatsapp/messages — veja Envio de mensagens.

Criar um template

O corpo segue o formato da Meta: o mesmo components que GET /v1/whatsapp/templates devolve.

curl -X POST https://api.superlead.app/v1/whatsapp/templates \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "confirmacao_consulta",
    "language": "pt_BR",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Olá {{1}}! Sua consulta está confirmada para {{2}}.",
        "example": { "body_text": [["Maria", "12/10 às 14h"]] }
      }
    ]
  }'

A resposta é o template, com o id que você usa nas demais rotas:

{
  "id": "tpl_1689556908129832",
  "name": "confirmacao_consulta",
  "language": "pt_BR",
  "category": "UTILITY",
  "status": "PENDING",
  "parameter_format": "POSITIONAL",
  "rejected_reason": null,
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{1}}! Sua consulta está confirmada para {{2}}.",
      "example": { "body_text": [["Maria", "12/10 às 14h"]] }
    }
  ]
}

Campo	Regra
`name`	Só minúsculas, números e `_`, até 512 caracteres. Único por idioma na sua conta.
`language`	Código do idioma na Meta, por exemplo `pt_BR`.
`category`	`MARKETING`, `UTILITY` ou `AUTHENTICATION`.
`parameter_format`	Opcional. `POSITIONAL` (variáveis como `{{1}}`, padrão) ou `NAMED` (variáveis como `{{nome}}`).
`components`	De 1 a 10 componentes (`HEADER`, `BODY`, `FOOTER`, `BUTTONS`), cada um com `type`. Toda variável precisa de um valor de exemplo. Só um componente `HEADER` por template: mais de um retorna `400 invalid_request`, ao criar e ao editar.

A Meta decide a categoria. Se ela entender que um template pedido como UTILITY é promocional, ele é aprovado como MARKETING — o que muda o preço de cada envio. Confira sempre o category da resposta e do evento de aprovação.

Nome e idioma são únicos na conta: repetir a criação retorna 409 template_already_exists. Por isso a criação não usa Idempotency-Key.

Cabeçalho de imagem, vídeo ou documento

Para aprovar um cabeçalho de mídia, a Meta exige um arquivo de exemplo. Envie uma URL pública do arquivo em example.header_handle — a Superlead baixa e entrega à Meta:

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": { "header_handle": ["https://seusite.com/arquivos/banner-outubro.jpg"] }
}

Formato	Tipos aceitos	Tamanho máximo
`IMAGE`	JPEG, PNG	5 MB
`VIDEO`	MP4	16 MB
`DOCUMENT`	PDF	20 MB

A URL precisa ser https, pública e direta (sem login, sem página intermediária, sem porta nem usuário e senha no endereço), num host com endereço IPv4 e servindo o arquivo sem compressão. São seguidos até 3 redirecionamentos, e o download precisa terminar em 15 segundos. Se o arquivo não puder ser baixado ou não for aceito, a criação retorna 422 media_unsupported com o motivo na mensagem. Já uma URL http:// em header_handle nem chega a ser baixada: retorna 400 invalid_request, com o caminho do campo em details (por exemplo components.0.example.header_handle.0), e não media_unsupported.

Esse arquivo é só o exemplo usado na aprovação. A mídia de cada envio é informada na hora, em POST /v1/whatsapp/messages.

Acompanhar a aprovação

Consulte o estado atual a qualquer momento:

curl https://api.superlead.app/v1/whatsapp/templates/tpl_1689556908129832 \
  -H "Authorization: Bearer sk_SUA_CHAVE"

`status`	Significado
`PENDING`	Em análise pela Meta. Não pode ser enviado nem editado.
`APPROVED`	Aprovado. Pode ser enviado.
`REJECTED`	Recusado. `rejected_reason` traz o motivo; edite para reenviar à análise.
`PAUSED`	Pausado pela Meta por baixa qualidade. Não pode ser enviado durante a pausa.
`DISABLED`	Desabilitado pela Meta por feedback negativo.

A Meta pode devolver outros valores (IN_APPEAL, PENDING_DELETION…). Trate os que não conhecer como “não enviável”. Para ser avisado em vez de consultar, assine o evento whatsapp.template.updated — veja Webhooks.

Editar

PATCH /v1/whatsapp/templates/{id} aceita category e/ou components:

curl -X PATCH https://api.superlead.app/v1/whatsapp/templates/tpl_1689556908129832 \
  -H "Authorization: Bearer sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "components": [
      {
        "type": "BODY",
        "text": "Olá {{1}}! Confirmamos sua consulta para {{2}}. Até lá!",
        "example": { "body_text": [["Maria", "12/10 às 14h"]] }
      }
    ]
  }'

components substitui a lista inteira. Mande o template completo como deve ficar, não só o que mudou. Num template com cabeçalho de mídia, reenvie o cabeçalho com uma URL do arquivo de exemplo — pode ser a própria URL que GET /v1/whatsapp/templates/{id} devolve em example.header_handle.
Nome e idioma não mudam. São a identidade do template; para outro nome, crie outro template.
Só APPROVED, REJECTED e PAUSED aceitam edição. Em análise, a edição retorna 409 template_status_conflict.
Limites da Meta para template aprovado: 1 edição a cada 24 horas e 10 em 30 dias; a categoria de um aprovado não pode mudar. Recusados e pausados não têm limite.

A resposta traz o status que a Meta atribuiu depois da edição — acompanhe o resultado final pelo webhook.

Excluir

curl -X DELETE https://api.superlead.app/v1/whatsapp/templates/tpl_1689556908129832 \
  -H "Authorization: Bearer sk_SUA_CHAVE"

{ "id": "tpl_1689556908129832", "deleted": true }

Exclui só o idioma daquele id. Versões do mesmo nome em outros idiomas continuam.
É bloqueada enquanto houver campanha agendada, em andamento ou pausada usando o template: 409 template_in_use, com até 10 campanhas em details.
Template desabilitado pela Meta não pode ser excluído: 409 template_status_conflict.

A exclusão não pode ser desfeita, e a Meta impede recriar por 30 dias o nome de um template aprovado que foi excluído.

Erros desta área

Código	HTTP	Quando acontece
`template_not_found`	404	Nenhum template com esse id na sua conta.
`template_already_exists`	409	Nome e idioma já existem (ou ainda estão em exclusão).
`template_in_use`	409	Exclusão bloqueada por campanha ativa.
`template_status_conflict`	409	O status atual não permite a operação.
`template_invalid`	422	A Meta recusou a definição; quando ela envia uma explicação, vem em `details`.
`template_limit_reached`	422	A conta atingiu o teto de templates.
`media_unsupported`	422	O arquivo de exemplo não pôde ser baixado ou não é aceito.

Quando a Meta recusa a definição e envia uma explicação, ela vem em details, com path: "meta":

{
  "error": {
    "code": "template_invalid",
    "message": "Meta refused this template definition. See details.",
    "request_id": "req_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "upstream_code": 100,
    "details": [
      { "path": "meta", "message": "o componente do tipo BODY não contém o(s) campo(s) esperado(s) (example)" }
    ]
  }
}

O catálogo completo está em Tratamento de erros.

Comece aqui

Conceitos

Criar um template

Cabeçalho de imagem, vídeo ou documento

Acompanhar a aprovação

Editar

Excluir

Erros desta área

​Criar um template

​Cabeçalho de imagem, vídeo ou documento

​Acompanhar a aprovação

​Editar

​Excluir

​Erros desta área

Criar um template

Cabeçalho de imagem, vídeo ou documento

Acompanhar a aprovação

Editar

Excluir

Erros desta área