Quais rotas fazem parte do scheduler?

O conjunto tem operações para agendar, consultar, cancelar, pausar e retomar. As rotas usam autenticação da instância pelo header token ou por Authorization: Bearer SEU_TOKEN. O identificador da instância vem dessa autenticação.

Rota O que faz
POST /scheduler/schedule Agenda uma mensagem para uma data e hora.
POST /scheduler/delay Agenda uma mensagem após um atraso em milissegundos.
GET /scheduler/pending Lista agendamentos pendentes; aceita filtro opcional jid.
DELETE /scheduler/{id} Cancela um agendamento pelo ID.
DELETE /scheduler/cancel-all Cancela todos os agendamentos pendentes da instância.
POST /scheduler/pause Pausa o scheduler da instância.
POST /scheduler/resume Retoma o scheduler da instância.

Todos os exemplos usam https://SEU-DOMINIO/ como domínio ilustrativo e SEU_TOKEN como credencial fictícia. Substitua ambos pelos dados da sua instância.

Como informar data e fuso horário?

POST /scheduler/schedule requer jid, content_type, content e scheduled_at. A data deve seguir RFC3339 e incluir offset, por exemplo 2026-10-10T15:00:00-03:00. O serviço armazena o instante em UTC. O campo timezone é opcional e guardado como uma string separada.

Este exemplo agenda conteúdo de texto para um JID de telefone:

curl -X POST 'https://SEU-DOMINIO/scheduler/schedule' \
  -H 'Content-Type: application/json' \
  -H 'token: SEU_TOKEN' \
  --data '{"jid":"[email protected]","content_type":"text","content":{"text":"Lembrete: reunião hoje às 15h"},"scheduled_at":"2026-10-10T15:00:00-03:00"}'

O offset faz parte da data enviada e determina o instante representado. Se a aplicação já trabalha com um fuso local, converta a hora desejada para uma data RFC3339 com o offset correspondente antes da chamada.

Embora timezone exista como campo opcional, seu formato exigido e uma eventual conversão para definir o instante não estão documentados. Não dependa desse campo para corrigir um offset ausente: inclua o offset no próprio scheduled_at.

Por exemplo, a data local das 15h com offset -03:00 representa um instante distinto de 15h em UTC. Como o armazenamento é em UTC, mantenha no sistema de origem tanto a intenção local quanto a data enviada se sua interface precisar apresentar a hora original. O campo opcional separado não muda a exigência de scheduled_at RFC3339 com offset.

Que tipos de conteúdo podem ser agendados?

O campo content_type aceita text, media, location, contact, interactive, status, group_status e channel_status, sem distinção de maiúsculas após normalização. O campo content precisa ser um objeto validado conforme o tipo. Para status, o JID deve ser status@broadcast; status de grupo usa JID terminado em @g.us; status de canal usa JID terminado em @newsletter. O tipo interactive não agenda em canais.

O JID identifica o destino do agendamento. Para uma conversa individual, o exemplo usa um JID de telefone terminado em @s.whatsapp.net; destinos de grupo e canal seguem sufixos próprios quando os tipos de status correspondentes são usados. O scheduler valida o conteúdo conforme o tipo, portanto não trate content como texto arbitrário para todos os formatos. Escolha content_type conforme a operação planejada e envie um objeto compatível com aquele tipo.

Para atraso relativo, use /scheduler/delay com jid, content_type, content e delay_ms inteiro. O valor representa milissegundos somados ao horário atual:

curl -X POST 'https://SEU-DOMINIO/scheduler/delay' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  --data '{"jid":"[email protected]","content_type":"text","content":{"text":"Lembrete em quinze minutos"},"delay_ms":900000}'

Os fatos disponíveis não estabelecem um limite máximo de atraso nem uma regra explícita para valores negativos. Faça a validação do prazo no seu sistema e use atrasos com unidade clara. Para formatos de texto e mídia em envio direto, veja exemplos de envio pela API; a seleção de conteúdo está no guia de tipos de mensagem WhatsApp API.

Como acompanhar e cancelar uma mensagem?

GET /scheduler/pending lista os agendamentos pendentes da instância. A query jid é opcional: com ela, restringe a lista ao JID informado; sem ela, retorna os pendentes da instância. A resposta contém success, count e messages.

curl 'https://SEU-DOMINIO/scheduler/pending?jid=5511999999999%40s.whatsapp.net' \
  -H 'token: SEU_TOKEN'

Para cancelar uma entrada específica, use o ID do agendamento no caminho:

curl -X DELETE 'https://SEU-DOMINIO/scheduler/ID_DO_AGENDAMENTO' \
  -H 'token: SEU_TOKEN'

O cancelamento individual responde com success. Para interromper todos os pendentes da instância, use DELETE /scheduler/cancel-all; a resposta também informa quantos foram cancelados. A API não documenta cancelamento por JID: o filtro por JID serve para listar, enquanto o cancelamento individual é por ID e a limpeza ampla atua sobre a instância autenticada.

Uma rotina de controle pode listar os pendentes, apresentar o ID retornado para a equipe e, após a decisão, enviar a exclusão daquele ID. Isso mantém clara a diferença entre escolher mensagens de uma conversa para visualização e executar o cancelamento efetivamente disponível. A resposta de cancelamento sinaliza a operação do scheduler, mas não altera o histórico de mensagens já processadas.

Como pausar e retomar a fila?

POST /scheduler/pause pausa o scheduler da instância e POST /scheduler/resume retoma o processamento. Essas rotas não usam campos de body. A fila aplica um limite por instância; quando a configuração está ausente ou não é positiva, o padrão é 1.000 agendamentos pendentes.

Trate a resposta da requisição como confirmação da operação da API, sem inferir que a mensagem futura foi entregue ou lida. Para integrar observabilidade de eventos além da consulta dos pendentes, veja webhooks e SSE da GoZAP.

Planeje também como sua aplicação reage se a fila atingir o limite configurado. O valor padrão documentado é por instância e não substitui acompanhamento de pendências em operações que agendam muitos itens. Pause ou retome o scheduler de forma intencional, e mantenha registro das respostas para relacionar cada solicitação ao ID usado em consultas e cancelamentos.

Inclua no desenho da integração o ciclo completo: criar o agendamento, reter o identificador recebido, listar pendências quando for necessário verificar o estado e cancelar pelo ID se a decisão operacional mudar. Para consultar por JID, codifique corretamente o parâmetro de URL. A listagem por JID ajuda a localizar entradas relacionadas a uma conversa, mas não substitui o identificador requerido pela rota de cancelamento individual.

Quando não escolher a GoZAP

Não escolha a GoZAP se seu fluxo exige cancelamento por JID, regras de fuso cuja conversão dependa do campo timezone, ou precisão de execução em horário exato que não esteja formalizada para sua operação. Projete a aplicação com base no ID retornado pelo agendamento e no offset enviado na data. A GoZAP conecta pelos modos nativos Web e Mobile, ambos fora da API oficial da Meta.