> ## Documentation Index > Fetch the complete documentation index at: https://docs.superlead.app/llms.txt > Use this file to discover all available pages before exploring further. # Templates > Crie templates pela API, acompanhe a aprovação da Meta, edite e exclua. 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. **1. 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. **2. 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}`. **3. Envie** Com `status: "APPROVED"`, use o `name` e o `language` do template em `POST /v1/whatsapp/messages` — veja [Envio de mensagens](https://docs.superlead.app/guias/envio-de-mensagens.md). ## Criar um template O corpo segue o **formato da Meta**: o mesmo `components` que `GET /v1/whatsapp/templates` devolve. ```bash theme={null} 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: ```json theme={null} { "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. | > [!WARNING] > > **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: ```json theme={null} { "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`. > [!NOTE] > > 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: ```bash theme={null} 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](https://docs.superlead.app/guias/webhooks.md#evento-whatsapp-template-updated). ## Editar `PATCH /v1/whatsapp/templates/{id}` aceita `category` e/ou `components`: ```bash theme={null} 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 ```bash theme={null} curl -X DELETE https://api.superlead.app/v1/whatsapp/templates/tpl_1689556908129832 \ -H "Authorization: Bearer sk_SUA_CHAVE" ``` ```json theme={null} { "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`. > [!WARNING] > > 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"`: ```json theme={null} { "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](https://docs.superlead.app/guias/erros.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.