Agendar mensagens pela API do WhatsApp

A Cloud API da Meta não tem agendamento: ela envia no momento da chamada. O agendamento é um recurso da camada do Joinotify — o mesmo endpoint de envio aceita um instante absoluto ou um atraso relativo, guarda o pedido e entrega na hora certa. A resposta é 202, e não 201, porque nada foi criado na Meta ainda.

Duas formas de agendar, e por que as duas existem

• sendAt — um instante absoluto. É o caso de "sexta às 9h".
• delaySeconds — um atraso a partir de agora. É o caso de "duas horas depois do carrinho abandonado".

Converter um no outro do lado do cliente é justamente onde entram os erros de fuso horário — por isso os dois existem.

# Daqui a duas horas
curl -X POST https://api.joinotify.com/messages \
  -H 'Authorization: Bearer sk_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "text",
    "to": "5541987111527",
    "body": "Seu carrinho ainda está separado 🙂",
    "delaySeconds": 7200
  }'

A resposta traz o identificador do agendamento e o instante calculado:

{
  "data": {
    "id": "clz3k1p9x0000",
    "status": "pending",
    "to": "5541987111527",
    "sendAt": "2026-08-15T21:00:00.000Z",
    "messageId": null
  }
}

O messageId é nulo porque a mensagem ainda não existe na Meta. Ele é preenchido quando o envio de fato acontece — e é o wamid que casa com os eventos de entrega.

Listar e cancelar

# O que está pendente
curl https://api.joinotify.com/messages/scheduled?status=pending \
  -H 'Authorization: Bearer sk_live_xxx'

# Cancelar
curl -X DELETE https://api.joinotify.com/messages/scheduled/clz3k1p9x0000 \
  -H 'Authorization: Bearer sk_live_xxx'

O cancelamento vale mesmo faltando segundos: quem entrega relê o registro antes de sair. Uma mensagem já enviada responde 404 — não há o que cancelar.

O cancelamento é o recurso, não um detalhe

Agendar é fácil; o valor está em conseguir desistir. Os casos que aparecem em produção são quase sempre de cancelamento:

• O carrinho foi recuperado antes das duas horas — cancele a mensagem de recuperação.
• O pedido foi cancelado antes do lembrete de pagamento.
• O cliente respondeu e o assunto se resolveu antes do follow-up agendado.
• A campanha foi suspensa e há centenas de envios pendentes.

Guarde o id do agendamento junto do registro que o originou. Sem isso, cancelar significa listar tudo e adivinhar qual é qual.

O que é reconferido na hora de enviar

Três coisas, e nenhuma delas no momento do agendamento:

1. O direito de uso — uma assinatura que caiu no meio do caminho impede o envio.
2. O número — ele pode ter sido desconectado entre o agendamento e a entrega.
3. As regras da mensagem — a janela de 24 horas é avaliada na hora do envio, não na hora do agendamento.

O terceiro item é o que mais surpreende. Agendar um texto livre para daqui a 20 horas parece seguro se a janela está aberta agora, mas ela pode ter fechado quando a mensagem sair. Para envio agendado longe, use template.

Quando agendar e quando usar fila própria

• Agende na API quando o atraso é do negócio: lembrete, follow-up, recuperação, aviso na véspera.
• Use fila própria quando o atraso é técnico: retentativa com backoff, limitação de vazão, ordenação de lote.

Misturar os dois — agendar mil mensagens para o mesmo minuto — troca um problema por outro: o limite de envio do número continua valendo na hora da entrega.

Perguntas frequentes

A API oficial da Meta agenda mensagens?

Não. O agendamento é da camada do provedor; a Cloud API envia no momento da chamada.

Posso agendar template?

Pode, e é o recomendado para agendamentos distantes — texto livre depende da janela de 24 horas estar aberta na hora do envio.

O que acontece se a assinatura vencer antes do envio?

O envio não acontece. O direito de uso é reconferido na hora de enviar, não na hora de agendar.

Dá para editar uma mensagem agendada?

O caminho é cancelar e agendar de novo — o que também deixa o histórico mais claro do que uma edição silenciosa.