Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://developer.zapsterapi.com/llms.txt

Use this file to discover all available pages before exploring further.

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