> ## 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. # Criar Template > Cria um template na sua conta WhatsApp Business e o envia para aprovação da Meta. O corpo segue o **formato da Meta**: o mesmo `components` que `GET /v1/whatsapp/templates` devolve. - A aprovação é **assíncrona** (de minutos a 24 horas). O template normalmente nasce com `status: "PENDING"` — a resposta traz o status lido na Meta; acompanhe por `GET /v1/whatsapp/templates/{id}` ou pelo webhook `whatsapp.template.updated`. - A Meta pode atribuir uma **categoria diferente** da pedida. A resposta traz a categoria que valeu. - **Cabeçalho de mídia**: em `example.header_handle[0]`, envie uma URL `https` pública do arquivo de exemplo — a Superlead baixa e entrega à Meta. Limites: imagem JPEG/PNG até 5 MB, vídeo MP4 até 16 MB, documento PDF até 20 MB. - Só um componente `HEADER` por template; mais de um retorna `400`. - Nome + idioma são únicos na conta: repetir a criação retorna `409 template_already_exists`. Veja o guia de [Templates](/guias/templates). ## OpenAPI ````yaml /openapi.json post /v1/whatsapp/templates openapi: 3.1.0 info: title: Superlead API version: 1.0.0 description: > API oficial do Superlead para envio de mensagens WhatsApp aos **seus leads**. ## Autenticação Toda chamada exige `Authorization: Bearer sk_...` (crie a chave no painel Superlead em Integrações → API). A chave é escopada à sua empresa. ## Início rápido ```bash curl -X POST https://api.superlead.app/v1/whatsapp/messages \ -H "Authorization: Bearer sk_SUACHAVE" \ -H "Idempotency-Key: pedido-8734" \ -H "Content-Type: application/json" \ -d '{"to":"+5511999999999","type":"text","text":{"body":"Olá!"}}' ``` No n8n: nó **HTTP Request**, método POST, header Authorization como acima. ## Endereçamento O campo `to` aceita **telefone E.164** (`+5511999999999`) ou **BSUID** (`BR.13491208655302741918` — o `fromUserId` entregue nos webhooks quando o contato usa username do WhatsApp; usernames nunca endereçam). O destinatário precisa ser um lead existente da sua empresa — o envio nunca cria leads. Para outreach, crie antes com `POST /v1/leads`. Use `external_id` para reconciliar com o seu sistema. ## Janela de 24h (regra da Meta) Mensagens de formato livre (text, image, ...) só são entregues se o lead falou com você nas últimas 24 horas. Fora da janela, use `type: "template"` com um template aprovado (liste-os em `GET /v1/whatsapp/templates`). Fora da janela a Meta pode rejeitar o envio na hora (`outside_24h_window`) OU aceitá-lo (201, status `accepted`) e falhá-lo de forma assíncrona segundos depois — a mensagem passa ao status `failed`. Confirme em `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated`. ## Idempotência Envie o header `Idempotency-Key` (recomendado). Retries com a mesma chave e mesmo body retornam a resposta original sem reenviar. Validade: 24h. ## Rate limit 60 requisições/min por chave (headers `X-RateLimit-*`; `429` inclui `Retry-After`). Cota diária por empresa: 10.000 leituras (GET) e 10.000 escritas (POST, PATCH, PUT, DELETE), zerada à meia-noite de Brasília (headers `X-Daily-Quota-*`; `429 daily_quota_exceeded` inclui `Retry-After`). ## Status da mensagem A resposta traz o status inicial. Acompanhe `sent → delivered → read` (ou `failed`) pelos webhooks do Superlead (evento `whatsapp.message.updated`) ou por `GET /v1/whatsapp/messages/{id}`. O evento de status identifica a mensagem pelo `wamid` retornado na resposta do envio. ## Erros Envelope estável `{ "error": { "code", "message", "request_id" } }`. Trate códigos desconhecidos pelo HTTP status (novos códigos são mudança aditiva). | HTTP | code | Meaning | |---|---|---| | 400 | `invalid_request` | The request body is invalid. Check the details field and the API reference. | | 401 | `invalid_api_key` | Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. | | 404 | `lead_not_found` | No lead matches this recipient in your company. The API only messages existing leads. | | 404 | `message_not_found` | No message with this id exists in your company. | | 404 | `stage_not_found` | No funnel stage with this id exists in your company. List valid stages with GET /v1/funnel/stages. | | 409 | `idempotency_conflict` | This Idempotency-Key was already used with a different request body, or the original request is still in progress. | | 409 | `lead_already_exists` | A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages. | | 422 | `funnel_not_configured` | Your company has no funnel stages configured. Set up the funnel in the Superlead panel first. | | 422 | `no_active_connection` | Your company has no active WhatsApp connection. Connect a number in the Superlead panel first. | | 422 | `connection_expired` | Your WhatsApp connection is no longer authorized. Reconnect it in the Superlead panel. | | 422 | `channel_capability_unsupported` | Your company's WhatsApp connection type does not support this operation. | | 422 | `outside_24h_window` | Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead. | | 422 | `template_not_found` | Template not found. Check the exact name and language with GET /v1/whatsapp/templates. | | 422 | `template_params_invalid` | Template parameters do not match the approved template. Check count, format and language. | | 422 | `recipient_unavailable` | The recipient cannot receive this message on WhatsApp right now. | | 422 | `media_unsupported` | WhatsApp could not fetch or process the media. Check that the link is public and direct, the format is supported and the file is within the size limit for its type. | | 422 | `message_blocked` | Meta blocked this message (spam or ecosystem limits). Reduce volume to this recipient and review quality. | | 429 | `rate_limit_exceeded` | Rate limit for this API key exceeded. Retry after the time in the Retry-After header. | | 429 | `daily_quota_exceeded` | Daily quota for this company exceeded. It resets at midnight America/Sao_Paulo. Retry after the time in the Retry-After header. | | 429 | `channel_rate_limit` | WhatsApp is throttling your number. Slow down and retry later. | | 502 | `channel_error` | The messaging provider returned an unexpected error. Our team was notified; retry later. | | 500 | `internal_error` | Internal error. Our team was notified; retry later. | ## Versionamento Caminho `/v1/`. Mudanças incompatíveis só em `/v2/`. Campos novos opcionais podem aparecer a qualquer momento — ignore campos desconhecidos. servers: - url: https://api.superlead.app description: Produção security: [] paths: /v1/whatsapp/templates: post: summary: Criar Template description: >- Cria um template na sua conta WhatsApp Business e o envia para aprovação da Meta. O corpo segue o **formato da Meta**: o mesmo `components` que `GET /v1/whatsapp/templates` devolve. - A aprovação é **assíncrona** (de minutos a 24 horas). O template normalmente nasce com `status: "PENDING"` — a resposta traz o status lido na Meta; acompanhe por `GET /v1/whatsapp/templates/{id}` ou pelo webhook `whatsapp.template.updated`. - A Meta pode atribuir uma **categoria diferente** da pedida. A resposta traz a categoria que valeu. - **Cabeçalho de mídia**: em `example.header_handle[0]`, envie uma URL `https` pública do arquivo de exemplo — a Superlead baixa e entrega à Meta. Limites: imagem JPEG/PNG até 5 MB, vídeo MP4 até 16 MB, documento PDF até 20 MB. - Só um componente `HEADER` por template; mais de um retorna `400`. - Nome + idioma são únicos na conta: repetir a criação retorna `409 template_already_exists`. Veja o guia de [Templates](/guias/templates). operationId: createWhatsAppTemplate requestBody: required: true content: application/json: schema: type: object required: - name - language - category - components additionalProperties: false properties: name: type: string pattern: ^[a-z0-9_]{1,512}$ description: >- Nome do template: só minúsculas, números e `_`, até 512 caracteres. É o valor usado em `template.name` no envio. example: confirmacao_consulta language: type: string minLength: 2 maxLength: 15 description: Código do idioma na Meta. example: pt_BR category: type: string enum: - MARKETING - UTILITY - AUTHENTICATION description: >- Categoria pedida. A Meta pode atribuir outra — confira a resposta. example: UTILITY parameter_format: type: string enum: - POSITIONAL - NAMED description: >- Como as variáveis são escritas: `POSITIONAL` (`{{1}}`, padrão) ou `NAMED` (`{{nome}}`). example: POSITIONAL components: type: array minItems: 1 maxItems: 10 description: >- Componentes do template no formato da Meta (`HEADER`, `BODY`, `FOOTER`, `BUTTONS`). Cada item precisa de `type`; o restante segue a documentação da Meta. Em cabeçalho de mídia, `example.header_handle[0]` aceita uma URL `https` pública do arquivo de exemplo. items: type: object required: - type additionalProperties: {} properties: type: type: string description: >- Tipo do componente: `HEADER`, `BODY`, `FOOTER` ou `BUTTONS`. example: BODY examples: texto: summary: Corpo com variáveis value: 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 botoes: summary: Cabeçalho de texto, rodapé e botões value: name: lembrete_pagamento language: pt_BR category: UTILITY components: - type: HEADER format: TEXT text: Lembrete de pagamento - type: BODY text: Olá {{1}}, sua fatura de {{2}} vence amanhã. example: body_text: - - Maria - R$ 199,00 - type: FOOTER text: Clínica Exemplo - type: BUTTONS buttons: - type: QUICK_REPLY text: Já paguei - type: URL text: Ver fatura url: https://seusite.com/faturas/{{1}} example: - https://seusite.com/faturas/8734 imagem: summary: Cabeçalho de imagem (exemplo por URL) value: name: promocao_outubro language: pt_BR category: MARKETING components: - type: HEADER format: IMAGE example: header_handle: - https://seusite.com/arquivos/banner-outubro.jpg - type: BODY text: Olá {{1}}! Outubro tem condição especial para você. example: body_text: - - Maria responses: '201': description: Template criado e enviado para aprovação. content: application/json: schema: type: object properties: id: type: string description: >- Id do template (`tpl_...`). Use nas rotas `/v1/whatsapp/templates/{id}`. example: tpl_1689556908129832 name: type: string description: Nome do template — use como `template.name` no envio. example: confirmacao_consulta language: type: - string - 'null' description: >- Código do idioma — use como `template.language.code` no envio. example: pt_BR category: type: - string - 'null' description: >- Categoria atribuída pela Meta (`MARKETING`, `UTILITY`, `AUTHENTICATION`). Pode ser diferente da que você pediu. example: UTILITY status: type: string description: >- Status na Meta (`APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`, `IN_APPEAL`, `PENDING_DELETION`...). Só `APPROVED` pode ser enviado. Valores novos podem surgir. example: APPROVED parameter_format: type: - string - 'null' description: >- Como as variáveis são escritas: `POSITIONAL` (`{{1}}`) ou `NAMED` (`{{nome}}`). example: POSITIONAL rejected_reason: type: - string - 'null' description: >- Motivo informado pela Meta quando `status` é `REJECTED`; `null` nos demais casos. example: null components: type: - array - 'null' description: >- Estrutura do template (cabeçalho, corpo, rodapé, botões) no formato da Meta. Em cabeçalho de mídia, o exemplo volta como uma URL temporária da Meta. items: type: object additionalProperties: {} example: 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 '400': description: >- `invalid_request` — corpo fora do formato. O campo `details` aponta cada problema. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: >- The request body is invalid. Check the details field and the API reference. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 details: - path: name message: >- use only lowercase letters, digits and underscores (max 512 characters) '401': description: >- `invalid_api_key` — chave de API ausente, malformada ou revogada. Envie `Authorization: Bearer sk_...`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: >- Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '409': description: >- `template_already_exists` — já existe um template com esse nome e idioma na conta (ou ele ainda está em exclusão). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: template_already_exists message: >- A template with this name and language already exists, or is still being deleted, in your WhatsApp Business Account. Use a different name. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: 100 '422': description: >- `template_invalid` — a Meta recusou a definição; o motivo vem em `details`. `template_limit_reached` — teto de templates da conta. `media_unsupported` — o arquivo de exemplo não pôde ser baixado ou não é aceito. `no_active_connection`, `connection_expired`, `channel_capability_unsupported` — problemas da conexão WhatsApp. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: template_invalid message: Meta refused this template definition. See details. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: 100 details: - path: meta message: >- O parâmetro "components" do modelo de mensagem não contém alguns campos esperados: o componente do tipo BODY não contém o(s) campo(s) esperado(s) (example) '429': description: >- `rate_limit_exceeded` — limite de 60 requisições/min da chave excedido (aguarde o `Retry-After`). `daily_quota_exceeded` — a cota diária da empresa acabou; zera à meia-noite de Brasília (aguarde o `Retry-After`). `channel_rate_limit` — a Meta limita a criação a 100 templates por hora por conta. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: channel_rate_limit message: >- Meta limits template creation to 100 per hour per WhatsApp Business Account. Retry later. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: 4 security: - apiKey: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string description: >- Código estável do erro (ex.: `lead_not_found`). Novos códigos podem surgir a qualquer momento — trate códigos desconhecidos pelo HTTP status. example: lead_not_found message: type: string description: >- Descrição legível do erro, em inglês. O texto pode mudar — não faça parsing dele; use `code`. request_id: type: string description: >- Id único desta requisição. Inclua ao reportar um problema ao suporte. example: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: type: number description: >- Código numérico original da Meta, presente quando o erro veio do WhatsApp (ex.: `131047` para fora da janela de 24h). example: 131047 details: type: array description: >- Detalhes do erro. Aparece em três casos: erros de validação campo a campo em `400 invalid_request` (`path` é o campo do body); a explicação da Meta numa recusa de template, com `path: "meta"` (só quando a Meta envia uma explicação); e as campanhas que bloqueiam a exclusão de um template (`template_in_use`), com `path: "campaigns"` (até 10). items: type: object properties: path: type: string description: >- Em `invalid_request`, o caminho do campo inválido no body (ex.: `text.body`). Nas recusas de template vale `meta`; em `template_in_use` vale `campaigns`. message: type: string description: O que está errado com o campo. securitySchemes: apiKey: type: http scheme: bearer description: >- Chave de API da sua empresa (`sk_...`). Crie no painel Superlead em **Integrações → API** e envie em toda chamada como `Authorization: Bearer sk_...`. Veja [Autenticação](/guias/autenticacao). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.