Skip to main content

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.

Esta receita usa a API v3, a versão atual. Se você vem da v2, comece por O que a API v3 faz e como começar.

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 tokens-api.
  • Ao menos um modelo aprovado no canal (veja criar-modelo-mensagem).

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-modelo).

Passo a passo

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

    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.

    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.

  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:

    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

  • api-visao-geral
  • enviar-modelo
  • criar-modelo-mensagem