Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Enviar e receber

Agendar uma mensagem de WhatsApp pela API

Agende uma mensagem de WhatsApp por vez, até 30 dias à frente, com schedule; liste e cancele pelas rotas /schedules. Sem repetição.

5 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
Acrescente schedule: {"at": "2026-11-12T09:00:00-03:00"} a qualquer envio. A data precisa estar no futuro e a, no máximo, 30 dias. A resposta é 202 com schedule_id. É uma mensagem por vez, sem repetição, e a mídia só vale por url.

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:

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

json
{ "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 o error e a message do motivo, e você recebe o aviso automático message.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átis

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

js
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

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

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp