Recurso em beta: pode mudar. O agendamento é novo na versão 1.1.
Atualização de 12/11/2026 (provado em aparelho real): o agendamento de uma mensagem foi provado (a mensagem chegou na hora marcada). Listar e cancelar agendamentos seguem em beta.
Alguns avisos têm hora certa: o lembrete da consulta na véspera, a cobrança no dia do vencimento, o "bom dia" da campanha que o cliente pediu. Em vez de manter um cronômetro no seu sistema, você pode entregar a mensagem à API com a hora marcada.
Duas regras valem desde já, de propósito: uma mensagem por agendamento e nenhuma repetição. A ProxyBox não tem lista de transmissão, envio para todos nem agenda recorrente.
Como agendo uma mensagem?
Acrescentando schedule ao corpo de qualquer rota de envio, com at em ISO 8601 e o fuso.
Qualquer rota de envio (/messages/text, /messages/image e as demais) aceita o campo schedule:
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/messages/text" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{"to":"5547999999999","text":"Lembrete: sua consulta é amanhã às 9h.","schedule":{"at":"2026-11-12T09:00:00-03:00"}}'
at é uma data e hora ISO 8601 com o fuso (o -03:00 do exemplo é o horário de Brasília). Precisa estar no futuro e a, no máximo, 30 dias de distância.
A resposta é 202, e não 200, porque nada foi enviado ainda:
{ "ok": true, "schedule_id": 17, "run_at": "2026-11-12T09:00:00-03:00", "status": "pending" }
Guarde o schedule_id (um número): é com ele que você consulta e cancela.
Como listo, consulto e cancelo?
Com GET /schedules, GET /schedules/{id} e DELETE /schedules/{id}.
| Rota | O que faz |
|---|---|
GET /schedules |
Lista os agendamentos da instância; aceita status (pending, sent, failed ou canceled) e limit |
GET /schedules/{id} |
Mostra um agendamento |
DELETE /schedules/{id} |
Cancela, se ainda estiver pendente |
GET /schedules devolve data.schedules e data.total; cada item traz schedule_id, op, type, to, run_at, status, attempts e created_at, mais message_id e sent_at quando foi enviado, ou error e message quando falhou. O texto da mensagem não volta na consulta. Cada agendamento tem um estado: pending (esperando a hora), sent (enviado), failed (não foi possível enviar) ou canceled.
O que acontece na hora marcada?
A API envia pelo mesmo caminho do envio comum, com ritmo, pausa e trava; se estourar o limite, tenta de novo 5 minutos depois, até três vezes.
Um processo roda a cada minuto e envia o que venceu, pelo mesmo caminho do envio comum. Ou seja, valem o ritmo por minuto e por dia, a pausa entre mensagens e a trava de contato novo, como se você tivesse chamado a rota naquele instante.
- Passou do limite na hora? A API tenta de novo 5 minutos depois, até três vezes. Se não der, o agendamento vira
failed. - Falhou de vez? O agendamento vira
failed, com oerrore amessagedo motivo, e você recebe o aviso automáticomessage.scheduled_failed(veja o guia do aviso). Erros como número sem WhatsApp ou mídia inválida não são repetidos: falham na primeira vez. - A instância estava desconectada, em preparação ou o serviço fora do ar? Vale a mesma regra: nova tentativa 5 minutos depois, até três vezes.
Por isso, não marque dezenas de mensagens para o mesmo minuto: elas vão disputar o mesmo ritmo e algumas serão empurradas.
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisQuais são os limites e os erros?
Até 200 pendentes por instância, 30 dias à frente e mídia só por url.
- Até 200 agendamentos pendentes por instância.
- Mídia agendada só por
url: o arquivo é baixado na hora do envio, então o endereço precisa continuar no ar até lá. Base64 é recusado. - O conteúdo do agendamento fica guardado cifrado até a hora do envio.
| HTTP | error |
Quando |
|---|---|---|
| 422 | schedule_in_past |
A data já passou |
| 422 | schedule_too_far |
Mais de 30 dias à frente |
| 422 | schedule_limit |
Já existem 200 pendentes |
| 404 | not_found |
O schedule_id não existe |
| 409 | not_cancelable |
Tentou cancelar um que já foi enviado, falhou ou foi cancelado |
Qual é um exemplo em Node.js?
Agendar um lembrete e cancelá-lo se o cliente pagar antes.
const base = "https://proxybox.com.br/api/whatsapp/v1";
const h = { apikey: process.env.WA_KEY, "Content-Type": "application/json" };
const r = await fetch(`${base}/messages/text`, {
method: "POST", headers: h,
body: JSON.stringify({
to: "5547999999999",
text: "Seu boleto vence amanhã.",
schedule: { at: "2026-11-12T09:00:00-03:00" },
}),
});
const { schedule_id } = await r.json();
// se o cliente pagou antes:
await fetch(`${base}/schedules/${schedule_id}`, { method: "DELETE", headers: { apikey: h.apikey } });
Que boa prática vale para o agendamento?
Agende só para quem aceitou receber. A hora marcada não muda a regra do WhatsApp: mensagem para quem não espera continua gerando denúncia. Para o conjunto de cuidados, veja erros e limites.
Veja também
- Reagir, editar, apagar e status: API de WhatsApp
- Erros e limites da API de WhatsApp
- 13 modelos para a API de WhatsApp (Woo, Asaas)
Índice completo: documentação. Sobre o produto: uma instância de WhatsApp por número.
Autoria: equipe técnica da ProxyBox. Revisado em 11/11/2026 contra a versão 1.1 da API.