# Enviar um modelo (template) fora da janela de 24 h

No WhatsApp Oficial, você só pode mandar mensagem livre para um contato dentro de 24 horas da última mensagem dele. Passado esse prazo, a única forma de reabrir a conversa é enviar um **modelo** (template) já aprovado pela Meta. Esta receita mostra como listar os modelos disponíveis e enviar um pela API v3.

<p class="callout info">Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por <a href="/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar">O que a API v3 faz e como começar</a>.</p>

## Objetivo
Enviar um modelo aprovado para um contato fora da janela de 24 horas, pela API.

## Pré-requisitos
- Token de API com escopo **`messages:write`**: veja [Gerar tokens de API para integrações](/books/canais-e-integracoes/page/gerar-tokens-de-api-para-integracoes).
- Ao menos um modelo aprovado no canal (veja [Criar um modelo de mensagem (WhatsApp Oficial)](/books/modelos-tags-e-classificacoes/page/criar-um-modelo-de-mensagem-whatsapp-oficial)).

## Tempo estimado
10 minutos.

## Caminho de acesso
Chamada direta à API, não é a mesma tela de **Atendimentos → Enviar modelo**, que é a via manual (veja [Enviar um modelo de mensagem (WhatsApp Oficial)](/books/atendimentos/page/enviar-um-modelo-de-mensagem-whatsapp-oficial)).

## Passo a passo
1. Liste os modelos do canal para pegar o `id`, o `language` e as `variables` que ele espera:

   ```bash
   curl "https://api.atende.bot/public/v3/templates?channel=CHANNEL_ID" \
     -H "Authorization: Bearer SEU_TOKEN"
   ```

   Cada item traz `sendable: true` quando o modelo está aprovado e pronto para envio.

   <p class="callout info">Em canal não oficial (UazAPI/Z-API), esse filtro também devolve os modelos do tenant (que não pertencem a um canal específico e por isso servem para qualquer conversa não oficial).</p>

2. Envie pelo mesmo endpoint de mensagens, **não existe rota própria de template**: é `POST /public/v3/messages` com `template` em vez de `content`:

   ```bash
   curl -X POST https://api.atende.bot/public/v3/messages \
     -H "Authorization: Bearer SEU_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 8f14e45f-…" \
     -d '{
       "contact": "phone:5511999998888",
       "channel": "CHANNEL_ID",
       "template": "TEMPLATE_ID",
       "params": ["João", "pedido #4821"]
     }'
   ```

   `params` são os valores de `{{1}}`, `{{2}}`... do corpo aprovado, na ordem: a contagem precisa bater com a do modelo. `contact` aceita o uuid do contato ou o prefixo `phone:` com o telefone em E.164 (sem `+`), que cria o contato se ainda não existir.

3. Use `Idempotency-Key` (um UUID por envio) sempre que o fluxo puder retentar a chamada: a mesma chave com o mesmo corpo devolve a resposta original em vez de reenviar o modelo; com corpo diferente, `409 IDEMPOTENCY_KEY_REUSE`.

## Resultado esperado
`201` com a mensagem criada; o contato recebe o modelo mesmo com a janela de 24h fechada, e a conversa reabre.

## Erros comuns
- **Sintoma:** `400` de contagem de `params`. **Solução:** confira `variables` no `GET /templates`: a quantidade precisa bater exatamente.
- **Sintoma:** modelo não aparece na listagem. **Solução:** confira `sendable: true`: `approval_status` diferente de aprovado não pode ser enviado.

## Artigos relacionados
- [O que a API v3 faz e como começar](/books/api-e-integracoes/page/o-que-a-api-v3-faz-e-como-comecar)
- [Enviar um modelo de mensagem (WhatsApp Oficial)](/books/atendimentos/page/enviar-um-modelo-de-mensagem-whatsapp-oficial)
- [Criar um modelo de mensagem (WhatsApp Oficial)](/books/modelos-tags-e-classificacoes/page/criar-um-modelo-de-mensagem-whatsapp-oficial)