Agendamentos

Agendar é deixar a mensagem pronta para ser enviada no futuro, em uma data e hora que você escolher — sem precisar de ninguém clicando no momento do envio.

💡 Para que serve? Lembretes de consulta, confirmações de pedido, avisos de vencimento, follow-ups de venda... qualquer mensagem que precise chegar "depois".

🕐 Agendamentos × Agenda: qual é a diferença?

Existem dois grupos com nomes parecidos — não confunda:

📋 Os 4 endpoints

📮 A referência técnica completa de cada um está no arquivo OpenAPI — abaixo vão as informações essenciais em linguagem simples.

1️⃣ Criar um agendamento

Método: POST · Endereço: /schedule

O que preciso enviar

Regras importantes

• scheduledAt deve ser uma data futura, com no mínimo 5 minutos de antecedência;
• Sempre envie a data com fuso horário (offset) — datas sem timezone não são convertidas;
• Grupo e @lid precisam já existir como contato no sistema — nunca são criados automaticamente (números puros criam o contato sozinhos);
• Template oficial usa os mesmos templateComponents da API Oficial; mensagem com botões aceita no máximo 3 escolhas.

Exemplo simples (texto)

{
  "number": "5511999999999",
  "body": "Olá! Este é um lembrete agendado.",
  "scheduledAt": "2026-08-25T14:30:00-03:00"
}

Resposta e erros

• 201 — agendamento criado; a resposta traz id, status (PENDENTE), scheduledAt, destinatário, conteúdo e mais;
• 400 — dados inválidos (campo faltando, data no passado, botões/template malformados);
• 401 / 403 — token ausente/inválido ou não corresponde à conexão configurada;
• 404 — número não é um WhatsApp válido, ou grupo/@lid não existe como contato.

⏱️ O disparo acontece automaticamente pelo próprio sistema (verificação a cada ~1 minuto) — não há diferença de comportamento entre uma mensagem agendada pela tela do sistema e uma agendada pela API.

2️⃣ Listar agendamentos

Método: GET · Endereço: /schedules

Lista os agendamentos da conexão autenticada, 40 por página, do mais recente para o mais antigo.

Filtros opcionais (parâmetros na URL):

3️⃣ Consultar um agendamento

Método: GET · Endereço: /schedule/{id}

Retorna os dados atuais de um agendamento (status, data, destinatário etc.). Funciona também para agendamentos já enviados ou cancelados — útil para conferir o resultado depois do horário de disparo.

• 200 — dados do agendamento;
• 404 — não existe (ou pertence a outra empresa/conexão — os dados de terceiros nunca são retornados).

4️⃣ Cancelar um agendamento

Método: DELETE · Endereço: /schedule/{id}

Cancela um agendamento que ainda não foi enviado (status PENDENTE). O registro não é apagado — o status muda para CANCELADO e continua consultável.

• 200 — cancelado;
• 404 — não encontrado;
• 409 — já foi enviado (ENVIADA) ou já está cancelado — não pode mais cancelar.

🧪 Exemplo prático

Uma clínica quer lembrar os pacientes da consulta 24h antes. O sistema da clínica, ao marcar cada consulta, chama POST /schedule com o número do paciente, o texto do lembrete e a data/hora de 24h antes (com Idempotency-Key = código da consulta, para nunca duplicar). No horário marcado, o NextChat envia a mensagem automaticamente — e a clínica pode conferir o status depois com GET /schedule/{id}.

🆘 Problemas comuns

• "Erro 400 ao criar" — confira se scheduledAt está no futuro (mín. 5 minutos) e com fuso horário; se messageType é template/buttons, revise os campos próprios do tipo;
• "Erro 404 ao criar para um grupo" — o grupo/@lid precisa já existir como contato no sistema;
• "Erro 409 ao cancelar" — a mensagem já foi enviada ou o agendamento já estava cancelado;
• "Não apareceu na listagem" — a listagem é da conexão autenticada; confira o token e os filtros (number, status, período).