> ## 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.

# Mensagens Agendadas

> Como agendar o envio de mensagens do WhatsApp para uma data e hora futura

## 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:

1. Você envia um `POST /v1/wa/messages` com o campo `send_at` preenchido com a data e hora desejada
2. A Zapster armazena a mensagem e cria um agendamento interno
3. 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` |

<Note>
  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.
</Note>

## 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   |

Explicando cada linha:

* **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.

<Tip>
  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.
</Tip>