Execuções diferidas

Uma execução diferida é uma invocação que você agenda para acontecer uma única vez no futuro: um lembrete em 24 horas, um follow-up de carrinho abandonado, uma pesquisa 2 dias após a compra.

Cron ou diferida?

Cron — repete em um horário fixo (todos os dias às 9:00). Definido no código.
Diferida — acontece uma vez, em um momento calculado em tempo de execução (24 horas depois deste pedido). Agendada pelo handler ou pela requisição HTTP.

Agendar pelo handler

ctx.jelou.schedule() agenda uma execução relativa a “agora”:

index.ts

import { define, z } from "@jelou/functions";

export default define({
  name: "carrinho-abandonado",
  description: "Recebe o evento de carrinho abandonado e agenda o follow-up",
  input: z.object({
    userId: z.string(),
    carrinhoId: z.string(),
  }),
  handler: async (input, ctx) => {
    const booking = await ctx.jelou.schedule({
      in: "24h",
      path: "/enviar-followup",
      // Inclua o botId: no disparo não há canal resolvido
      payload: { userId: input.userId, carrinhoId: input.carrinhoId, botId: ctx.bot.id },
      key: `carrinho:${input.userId}:${input.carrinhoId}`,
      subject: `user_${input.userId}`,
    });

    ctx.log("Follow-up agendado", { id: booking.id, quando: booking.scheduledAt });
    return { agendado: true, id: booking.id };
  },
});

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`in`	`string \| number`	Sim	Duração: `"30m"`, `"24h"`, `"1h30m"`, `"3d"` ou segundos
`path`	`string`	Sim	Rota da sua função que será executada. Começa com `/`
`payload`	`object \| array`	Não	Dados que o handler recebe no disparo
`key`	`string`	Não	Etiqueta para buscar ou cancelar depois
`subject`	`string`	Não	Audiência, normalmente o ID do usuário
`idempotencyKey`	`string`	Não	Evita agendar duas vezes em retentativas
`pinDeployment`	`boolean`	Não	Fixa a execução na implantação atual

A duração aceita unidades compostas da maior para a menor: "1h30m" é válido, "30m1h" não.

Para follow-ups muito curtos use 5 segundos ou mais. Abaixo disso, a latência de rede pode deixar o momento agendado no passado e a plataforma rejeita.

Momento absoluto

ctx.jelou.scheduleAt() recebe uma data em vez de uma duração:

await ctx.jelou.scheduleAt({
  at: new Date("2026-12-24T18:00:00Z"), // ou a string ISO 8601
  path: "/felicitacao-natal",
  payload: { userId: input.userId },
});

Lança erro se a data já passou ou não pode ser interpretada. Os outros campos funcionam como em schedule().

Evitar duplicados

Se o serviço que chama sua função fizer retentativa, idempotencyKey garante um único agendamento:

const booking = await ctx.jelou.schedule({
  in: "24h",
  path: "/enviar-followup",
  payload: { userId: input.userId, carrinhoId: input.carrinhoId },
  idempotencyKey: `carrinho-abandonado:${input.eventoId}`,
});

if (booking.idempotentReplay) {
  ctx.log("Já estava agendado, não duplicou", { id: booking.id });
}

Reutilizar a mesma idempotencyKey com um payload diferente retorna erro 409.

Agendar por requisição HTTP

Qualquer cliente pode diferir uma chamada adicionando um header ao POST normal. Sem headers de agenda, a função executa imediatamente como sempre.

curl -X POST https://lembretes.fn.jelou.ai/enviar-lembrete \
  -H "Authorization: Bearer <sua-api-key>" \
  -H "X-Jelou-Schedule-In: 5m" \
  -H "X-Jelou-Key: lembrete:user-42" \
  -H "Content-Type: application/json" \
  -d '{"userId":"42","mensagem":"Sua consulta é amanhã"}'

Header	Efeito
`X-Jelou-Schedule-In`	Duração (`"5m"`, `"1h30m"`, `"24h"` ou segundos)
`X-Jelou-Schedule-At`	Momento absoluto em ISO 8601
`X-Jelou-Key`	Etiqueta para buscar ou cancelar depois
`X-Jelou-Subject`	Audiência, normalmente o ID do usuário
`X-Jelou-Pin-Deployment`	`"true"` para fixar a implantação atual
`Idempotency-Key`	Evita agendar duas vezes em retentativas

A resposta é 202 Accepted quando o agendamento é criado e 200 OK quando uma retentativa reutiliza um agendamento existente. O corpo não pode passar de 64 KB.

Receber o disparo

Na hora marcada, sua função recebe o payload original na rota indicada. Use ctx.isScheduledFire para distinguir o disparo de uma requisição normal:

handler: async (input, ctx) => {
  if (ctx.isScheduledFire) {
    ctx.log("Execução diferida disparada");
  }
  // ...
}

Verificar antes de agir

Entre o agendamento e o disparo, a realidade pode mudar: o cliente já pagou, o template foi pausado, o usuário pediu descadastro. ctx.guard encadeia essas verificações e evita o envio se alguma falhar:

export default define({
  name: "enviar-followup",
  description: "Envia o follow-up de carrinho abandonado se ainda se aplica",
  input: z.object({
    userId: z.string(),
    carrinhoId: z.string(),
    botId: z.string(),
  }),
  handler: async (input, ctx) => {
    // O botId viajou no payload que você agendou antes
    const registro = ctx.templateRegistry.for(input.botId);

    return ctx.guard
      .when("semPagar", async () => !(await consultarCarrinho(input.carrinhoId)).pago)
      .when("templateAprovado", () => registro.has("carrinho_abandonado_v3"))
      .run(async () => {
        await ctx.jelou.sendTemplate({
          template: "carrinho_abandonado_v3",
          to: input.userId,
          params: ["María", `https://loja.com/recuperar?c=${input.carrinhoId}`],
        });
        return { enviado: true };
      });
  },
});

Se todas as verificações passam, .run() executa e o resultado é a resposta. Se alguma falha, a cadeia é interrompida e retorna { skipped: "<nome>" } sem executar o envio.

A cadeia termina com .run(handler), não com .then(). ctx.guard é uma cadeia nova em cada requisição.

Se o bot não viaja no payload, em um disparo diferido ctx.bot não está resolvido e ctx.templateRegistry fica sem canal associado. Inclua o botId no payload ao agendar e vincule com ctx.templateRegistry.for(botId). Veja templates do WhatsApp.

Consultar o que está agendado

ctx.jelou.findDeferred() lista as execuções pendentes da sua função:

const { data, total } = await ctx.jelou.findDeferred({
  subject: `user_${input.userId}`,
  status: "scheduled",
});

for (const linha of data) {
  ctx.log("pendente", linha.id, linha.scheduledAt, linha.key);
}

Campo	Descrição
`key`	Filtra por etiqueta exata
`subject`	Filtra por audiência
`status`	`"active"` (default), `"scheduled"`, `"firing"`, `"fired"`, `"cancelled"`, `"failed"`
`page` / `perPage`	Paginação. Default `20`, máximo `100`

Cancelar

ctx.jelou.cancelDefer() cancela em lote por audiência ou etiqueta. Exige exatamente um de subject, key ou keyPrefix:

// Descadastro do usuário: cancela todos os lembretes pendentes
const { cancelled, raced } = await ctx.jelou.cancelDefer({
  subject: `user_${input.userId}`,
});

ctx.log("descadastro processado", { cancelados: cancelled.length, em_curso: raced.length });

raced contém as execuções que já estavam disparando quando o cancelamento chegou — para essas, a verificação com ctx.guard no handler é a última defesa. Escreva seus handlers de forma idempotente. Antes de um cancelamento amplo, previsualize o alcance com dryRun:

const previa = await ctx.jelou.cancelDefer({
  keyPrefix: "promo-verao:",
  dryRun: true,
});

if (previa.wouldCancelCount < 5000) {
  await ctx.jelou.cancelDefer({ keyPrefix: "promo-verao:" });
}

Não existe “reagendar”: um agendamento é imutável. Para mudar a hora, cancele e agende de novo.

Teste local

schedule, scheduleAt, findDeferred e cancelDefer funcionam apenas em uma função implantada. Localmente lançam erro porque não há credenciais de plataforma. Para exercitar o fluxo com jelou functions dev, ative a simulação:

JELOU_FN_DEFER_DEV=1 jelou functions dev

Nesse modo os argumentos são validados, o agendamento é registrado nos logs e um resultado sintético é retornado — seu handler continua executando, mas nada real é agendado. Para testes unitários use createMockContext, cujo ctx.jelou registra as chamadas sem rede nem configuração.

Inspecionar pelo CLI

# Agendamentos ativos da função do projeto atual
jelou functions defer list

# Os que falharam
jelou functions defer list minha-fn --status failed

# Os de um usuário
jelou functions defer list minha-fn --subject user_42

# Detalhe de um agendamento (inclui o último erro)
jelou functions defer get dinv_01ksqbvyqpe0prt91exc97mh4n

Veja a referência do CLI.

Limites

Limite	Valor
Agendamentos ativos por empresa	1.000
Antecedência máxima	30 dias
Tamanho do `payload`	64 KB
Cancelamento em lote por chamada	10.000 correspondências

Agendamentos já disparados, cancelados ou falhos não contam no limite de ativos.

Problemas comuns

Não disparou
Enviou mesmo tendo cancelado
Erro em local
Agendou duas vezes

Consulte o status e o último erro do agendamento:

jelou functions defer get dinv_01ksqbvy... --payload

Se o status é failed, o campo de erro indica por que a entrega falhou. Se é cancelled, algo cancelou antes — revise suas chamadas a cancelDefer.

Um cancelamento que chega quando a execução já começou não a interrompe. Aparece em raced e seu handler executa.Por isso a verificação vai no handler, não só no cancelamento:

return ctx.guard
  .when("segueAtivo", async () => await usuarioAtivo(input.userId))
  .run(async () => { /* envio */ });

scheduleAt unavailable: platform credentials missing

Você está chamando a família schedule em local. Suba o servidor com JELOU_FN_DEFER_DEV=1 jelou functions dev para simular os agendamentos.

O serviço que chama sua função fez retentativa. Adicione idempotencyKey (ou o header Idempotency-Key) com um valor derivado do evento:

idempotencyKey: `carrinho-abandonado:${input.eventoId}`

Cron

Tarefas recorrentes em horário fixo.

Mensageria

Enviar WhatsApp e validar templates.

Webhooks

Verificar assinaturas de serviços externos.

CLI

Comandos defer list e defer get.

Primeiros Passos

Desenvolvedor

Jelou CLI

Mensagens Outbound

Gestão

Marketplace

Canais

Configuração

Faturamento

Agendar pelo handler

Parâmetros

Momento absoluto

Evitar duplicados

Agendar por requisição HTTP

Receber o disparo

Verificar antes de agir

Consultar o que está agendado

Cancelar

Teste local

Inspecionar pelo CLI

Limites

Problemas comuns

Cron

Mensageria

Webhooks

CLI

​Agendar pelo handler

​Parâmetros

​Momento absoluto

​Evitar duplicados

​Agendar por requisição HTTP

​Receber o disparo

​Verificar antes de agir

​Consultar o que está agendado

​Cancelar

​Teste local

​Inspecionar pelo CLI

​Limites

​Problemas comuns

Cron

Mensageria

Webhooks

CLI

Agendar pelo handler

Parâmetros

Momento absoluto

Evitar duplicados

Agendar por requisição HTTP

Receber o disparo

Verificar antes de agir

Consultar o que está agendado

Cancelar

Teste local

Inspecionar pelo CLI

Limites

Problemas comuns