O que são mensagens agendadas
Mensagens agendadas permitem que você envie uma mensagem via API hoje, mas ela só será entregue ao destinatário em uma data e hora que você escolher. Basta incluir o campo send_at na requisição de envio e a Zapster cuida do resto.
Isso funciona para qualquer tipo de mensagem: texto, mídia (imagem, áudio, vídeo, documento), templates e mensagens com botões. Você não precisa montar cron jobs, filas ou timers no seu sistema. A Zapster armazena a mensagem e garante o envio no horário certo.
Na prática, é como deixar uma mensagem programada no WhatsApp, só que via API e com controle total sobre o que acontece em cada etapa.
Casos de uso
- Lembretes de pagamento: agendar uma cobrança para o dia do vencimento da fatura
- Follow-ups de venda: mandar uma mensagem 2 dias após o primeiro contato com um lead
- Campanhas com horário definido: preparar tudo na segunda-feira e distribuir os envios ao longo da semana
- Confirmações de consulta: lembrar o paciente 1 dia antes do agendamento
- Onboarding de clientes: enviar dicas de uso nos primeiros dias após o cadastro
- Pesquisas de satisfação: disparar NPS alguns dias depois de uma compra ou atendimento
Como funciona
O fluxo é direto:
- Você envia um
POST /v1/wa/messages com o campo send_at preenchido com a data e hora desejada
- A Zapster armazena a mensagem e cria um agendamento interno
- No horário definido, a mensagem é enviada automaticamente pela instância configurada
Se o envio falhar (instância offline, número bloqueado, problema de rede), o sistema faz até 3 tentativas. Se todas falharem, o status da mensagem vai para failed e o campo errors traz os detalhes do problema.
Ciclo de vida da mensagem
Toda mensagem agendada passa pelos seguintes estados:
| De | Para | Quando acontece |
|---|
| — | scheduled | Mensagem criada via API com send_at |
scheduled | sent | Enviada com sucesso no horário agendado |
scheduled | failed | Falha no envio após 3 tentativas |
scheduled | canceled | Cancelada pelo usuário via DELETE /v1/wa/messages/:id |
Depois que a mensagem atinge o status sent, o sistema também registra os timestamps delivered_at (entrega confirmada no aparelho) e read_at (destinatário leu a mensagem). Mas o status continua como sent — entrega e leitura são rastreadas apenas por timestamps.
Limites por plano
| Essential | Pro | Enterprise |
|---|
| Agendadas simultâneas | 10 | 500 | 10.000 |
| Antecedência máxima | 7 dias | 1 ano | Sem limite |
| Retenção do histórico | 24 horas | 30 dias | 180 dias |
- Agendadas simultâneas: é o número de mensagens com status
scheduled que podem existir ao mesmo tempo na sua conta. Se você tem 10 mensagens pendentes no plano Essential, precisa esperar uma ser enviada (ou cancelar alguma) antes de agendar outra.
- Antecedência máxima: é o quão longe no futuro você pode agendar. No plano Essential, até 7 dias. No Pro, até 1 ano.
- Retenção do histórico: por quanto tempo você consegue consultar mensagens já enviadas. No Essential, apenas as últimas 24 horas ficam disponíveis para consulta.
Compatibilidade
Funciona com instâncias oficiais (WABA) e não oficiais (QR code). Não precisa mudar nada na configuração da sua instância para usar agendamento.
Sobre timezones
O campo send_at aceita datas no formato ISO 8601, que inclui informação de timezone. Na prática, você tem duas opções:
- Enviar com timezone explícito:
"2026-03-30T09:00:00-03:00" (horário de Brasília)
- Enviar em UTC:
"2026-03-30T12:00:00Z"
Os dois exemplos acima representam o mesmo momento. A diferença é só a forma de escrever.
A resposta da API sempre retorna datas em UTC, independente do timezone que você usou no envio.
Se você está no Brasil e não quer fazer conta de fuso horário, envie a data no horário local com -03:00 no final. Exemplo: "2026-03-30T09:00:00-03:00" para enviar às 9h da manhã no horário de Brasília.
