Pular para o conteúdo principal
Neste guia você vai agendar uma mensagem de WhatsApp para ser enviada em uma data futura. Leva menos de 5 minutos.

​
O que você vai precisar

  • Uma conta na Zapster API (se não tem, crie aqui)
  • Uma instância conectada (WABA ou não oficial)
  • Seu token de autenticação

​
1. Agendar uma mensagem

O campo send_at é o que transforma um envio comum em um agendamento. Passe a data e hora no formato ISO 8601 com fuso horário. 
curl -X POST https://api.zapsterapi.com/v1/wa/messages \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Instance-ID: SUA_INSTANCIA" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "5511999999999",
    "text": "Olá! Seu boleto vence amanhã.",
    "send_at": "2026-03-30T09:00:00-03:00"
  }'
Se a resposta voltar com status 201, a mensagem foi agendada. Guarde o message_id porque é com ele que você cancela ou consulta o status depois. Repare que o send_at na resposta vem em UTC, então -03:00 vira +3 horas no horário retornado.

​
2. Verificar o status

Para conferir se a mensagem ainda está na fila, use a listagem com filtros de data e status. 
curl "https://api.zapsterapi.com/v1/wa/messages?from=2026-03-30T00:00:00Z&to=2026-03-30T23:59:59Z&status=scheduled" \
  -H "Authorization: Bearer SEU_TOKEN"
Você vai ver a mensagem com status scheduled. Depois que o horário agendado passar, o status muda para sent (ou failed se algo deu errado no envio).

​
3. Cancelar se precisar

Mudou de ideia? Cancele com um DELETE passando o message_id. 
curl -X DELETE https://api.zapsterapi.com/v1/wa/messages/msg_k7m2nxp9q4 \
  -H "Authorization: Bearer SEU_TOKEN"
Só dá para cancelar mensagens que ainda não foram enviadas. Se a mensagem já saiu, o DELETE retorna erro 422.

​
Perguntas frequentes

Sim. O mínimo é 1 minuto no futuro. Se você passar uma data que já passou ou que está a menos de 1 minuto de distância, a API retorna erro de validação.
O sistema tenta enviar 3 vezes com intervalo crescente entre as tentativas. Se todas falharem, a mensagem vai para o status failed com o motivo do erro no campo errors.Quando a instância voltar, ela não reenvia automaticamente mensagens que já falharam. Você precisaria agendar novamente.
Não. Se você precisa alterar o texto, o destinatário ou o horário, cancele a mensagem existente com DELETE /v1/wa/messages/:id e crie uma nova.
Consulte o histórico com GET /v1/wa/messages e filtre por status=failed. O campo errors na resposta traz o código e a descrição do problema.Motivos comuns:
  • A instância estava desconectada no momento do envio
  • A janela de 24 horas do WABA expirou (erro 131047)
  • O template não foi encontrado (erro 132000)
  • O número do destinatário não existe ou está bloqueado
Depende do seu plano:
PlanoAgendadas simultâneasAntecedência máxima
Essential107 dias
Pro5001 ano
Enterprise10.000Sem limite
Se atingir o limite, a API retorna erro max_scheduled_messages_reached. Você pode cancelar mensagens pendentes para liberar espaço.
Esses campos dependem das configurações de privacidade do destinatário no WhatsApp. Se a pessoa desativou a confirmação de leitura, read_at nunca será preenchido. Se houve algum problema de rede, delivered_at pode demorar para aparecer.O status da mensagem continua como sent independente desses campos.
Sim, os dois tipos. Não precisa mudar nada na configuração. A API detecta automaticamente o tipo da instância e envia da forma correta.

​
Próximos passos