> ## 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.
# Como agendar sua primeira mensagem
> Tutorial passo a passo para enviar uma mensagem agendada via API
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](https://app.zapsterapi.com/signup))
* 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.
```bash cURL theme={null}
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"
}'
```
```javascript JavaScript (fetch) theme={null}
const response = await fetch('https://api.zapsterapi.com/v1/wa/messages', {
method: 'POST',
headers: {
'Authorization': 'Bearer SEU_TOKEN',
'X-Instance-ID': 'SUA_INSTANCIA',
'Content-Type': 'application/json',
},
body: JSON.stringify({
recipient: '5511999999999',
text: 'Olá! Seu boleto vence amanhã.',
send_at: '2026-03-30T09:00:00-03:00',
}),
});
const data = await response.json();
console.log(data);
// { message_id: "msg_k7m2nxp9q4", status: "scheduled", send_at: "2026-03-30T12:00:00.000Z" }
```
```python Python (requests) theme={null}
import requests
response = requests.post(
'https://api.zapsterapi.com/v1/wa/messages',
headers={
'Authorization': 'Bearer SEU_TOKEN',
'X-Instance-ID': 'SUA_INSTANCIA',
'Content-Type': 'application/json',
},
json={
'recipient': '5511999999999',
'text': 'Olá! Seu boleto vence amanhã.',
'send_at': '2026-03-30T09:00:00-03:00',
},
)
print(response.json())
# { "message_id": "msg_k7m2nxp9q4", "status": "scheduled", "send_at": "2026-03-30T12:00:00.000Z" }
```
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.
```bash cURL theme={null}
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"
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://api.zapsterapi.com/v1/wa/messages?from=2026-03-30T00:00:00Z&to=2026-03-30T23:59:59Z&status=scheduled',
{ headers: { 'Authorization': 'Bearer SEU_TOKEN' } }
);
const { data } = await response.json();
console.log(data);
```
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`.
```bash cURL theme={null}
curl -X DELETE https://api.zapsterapi.com/v1/wa/messages/msg_k7m2nxp9q4 \
-H "Authorization: Bearer SEU_TOKEN"
```
```javascript JavaScript theme={null}
await fetch('https://api.zapsterapi.com/v1/wa/messages/msg_k7m2nxp9q4', {
method: 'DELETE',
headers: { 'Authorization': 'Bearer SEU_TOKEN' },
});
// { id: "msg_k7m2nxp9q4", status: "canceled" }
```
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:
| Plano | Agendadas simultâneas | Antecedência máxima |
| ---------- | --------------------- | ------------------- |
| Essential | 10 | 7 dias |
| Pro | 500 | 1 ano |
| Enterprise | 10.000 | Sem 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
* [Veja todos os filtros disponíveis na listagem](/pt-BR/v1/api-reference/messages/list-messages)
* [Entenda o ciclo de vida das mensagens](/pt-BR/v1/concepts/message-lifecycle)
* [Limites e planos](/pt-BR/v1/concepts/scheduled-messages#limites-por-plano)