Ejecuciones diferidas

Una ejecución diferida es una invocación que agendas para que ocurra una sola vez en el futuro: un recordatorio a las 24 horas, un seguimiento de carrito abandonado, una encuesta 2 días después de la compra.

¿Cron o diferida?

Cron — se repite en un horario fijo (todos los días a las 9:00). Se define en el código.
Diferida — ocurre una vez, en un momento calculado en tiempo de ejecución (24 horas después de este pedido). Se agenda desde el handler o desde la petición HTTP.

Agendar desde el handler

ctx.jelou.schedule() agenda una ejecución relativa a “ahora”:

index.ts

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

export default define({
  name: "carrito-abandonado",
  description: "Recibe el evento de carrito abandonado y agenda el seguimiento",
  input: z.object({
    userId: z.string(),
    carritoId: z.string(),
  }),
  handler: async (input, ctx) => {
    const booking = await ctx.jelou.schedule({
      in: "24h",
      path: "/enviar-seguimiento",
      // Incluye el botId: en el disparo no hay canal resuelto
      payload: { userId: input.userId, carritoId: input.carritoId, botId: ctx.bot.id },
      key: `carrito:${input.userId}:${input.carritoId}`,
      subject: `user_${input.userId}`,
    });

    ctx.log("Seguimiento agendado", { id: booking.id, cuando: booking.scheduledAt });
    return { agendado: true, id: booking.id };
  },
});

Parámetros

Campo	Tipo	Requerido	Descripción
`in`	`string \| number`	Sí	Duración: `"30m"`, `"24h"`, `"1h30m"`, `"3d"` o segundos
`path`	`string`	Sí	Ruta de tu función que se ejecutará. Empieza con `/`
`payload`	`object \| array`	No	Datos que recibirá el handler al dispararse
`key`	`string`	No	Etiqueta para buscar o cancelar después
`subject`	`string`	No	Audiencia, normalmente el ID del usuario
`idempotencyKey`	`string`	No	Evita agendar dos veces si reintentas
`pinDeployment`	`boolean`	No	Fija la ejecución al despliegue actual

La duración acepta unidades compuestas de mayor a menor: "1h30m" es válido, "30m1h" no.

Para seguimientos muy cortos usa 5 segundos o más. Con duraciones menores la latencia de red puede dejar el momento agendado en el pasado y la plataforma lo rechaza.

Momento absoluto

ctx.jelou.scheduleAt() recibe una fecha en vez de una duración:

await ctx.jelou.scheduleAt({
  at: new Date("2026-12-24T18:00:00Z"), // o el string ISO 8601
  path: "/felicitacion-navidad",
  payload: { userId: input.userId },
});

Lanza un error si la fecha ya pasó o no se puede interpretar. El resto de campos funciona igual que en schedule().

Evitar duplicados

Si el servicio que llama a tu función reintenta, idempotencyKey garantiza una sola reserva:

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

if (booking.idempotentReplay) {
  ctx.log("Ya estaba agendado, no se duplicó", { id: booking.id });
}

Reusar la misma idempotencyKey con un payload distinto devuelve un error 409.

Agendar desde una petición HTTP

Cualquier cliente puede diferir una llamada agregando una cabecera al POST normal. Sin cabeceras de agenda, la función se ejecuta de inmediato como siempre.

curl -X POST https://recordatorios.fn.jelou.ai/enviar-recordatorio \
  -H "Authorization: Bearer <tu-api-key>" \
  -H "X-Jelou-Schedule-In: 5m" \
  -H "X-Jelou-Key: recordatorio:user-42" \
  -H "Content-Type: application/json" \
  -d '{"userId":"42","mensaje":"Tu cita es mañana"}'

Cabecera	Efecto
`X-Jelou-Schedule-In`	Duración (`"5m"`, `"1h30m"`, `"24h"` o segundos)
`X-Jelou-Schedule-At`	Momento absoluto en ISO 8601
`X-Jelou-Key`	Etiqueta para buscar o cancelar después
`X-Jelou-Subject`	Audiencia, normalmente el ID del usuario
`X-Jelou-Pin-Deployment`	`"true"` para fijar el despliegue actual
`Idempotency-Key`	Evita agendar dos veces al reintentar

La respuesta es 202 Accepted cuando se crea la reserva y 200 OK cuando un reintento reutiliza una reserva existente. El cuerpo no puede superar 64 KB.

Recibir el disparo

Cuando llega el momento, tu función recibe el payload original en la ruta que indicaste. Usa ctx.isScheduledFire para distinguir el disparo de una petición normal:

handler: async (input, ctx) => {
  if (ctx.isScheduledFire) {
    ctx.log("Ejecución diferida disparada");
  }
  // ...
}

Verificar antes de actuar

Entre el momento en que agendas y el momento en que se dispara, la realidad pudo cambiar: el cliente ya pagó, la plantilla se pausó, el usuario se dio de baja. ctx.guard encadena esas verificaciones y evita el envío si alguna falla:

export default define({
  name: "enviar-seguimiento",
  description: "Envía el seguimiento de carrito abandonado si sigue aplicando",
  input: z.object({
    userId: z.string(),
    carritoId: z.string(),
    botId: z.string(),
  }),
  handler: async (input, ctx) => {
    // El botId viajó en el payload que agendaste antes
    const registro = ctx.templateRegistry.for(input.botId);

    return ctx.guard
      .when("sinPagar", async () => !(await consultarCarrito(input.carritoId)).pagado)
      .when("plantillaAprobada", () => registro.has("carrito_abandonado_v3"))
      .run(async () => {
        await ctx.jelou.sendTemplate({
          template: "carrito_abandonado_v3",
          to: input.userId,
          params: ["María", `https://tienda.com/recuperar?c=${input.carritoId}`],
        });
        return { enviado: true };
      });
  },
});

Si todas las verificaciones pasan, se ejecuta .run() y su resultado es la respuesta. Si alguna falla, la cadena se corta y devuelve { skipped: "<nombre>" } sin ejecutar el envío.

La cadena termina con .run(handler), no con .then(). ctx.guard es una cadena nueva en cada petición.

Si el bot no viaja en el payload, en un disparo diferido ctx.bot no está resuelto y ctx.templateRegistry queda sin canal asociado. Incluye el botId en el payload al agendar y enlázalo con ctx.templateRegistry.for(botId). Ver plantillas de WhatsApp.

Consultar lo agendado

ctx.jelou.findDeferred() lista las ejecuciones pendientes de tu función:

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

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

Campo	Descripción
`key`	Filtra por etiqueta exacta
`subject`	Filtra por audiencia
`status`	`"active"` (default), `"scheduled"`, `"firing"`, `"fired"`, `"cancelled"`, `"failed"`
`page` / `perPage`	Paginación. Default `20`, máximo `100`

Cancelar

ctx.jelou.cancelDefer() cancela en bloque por audiencia o etiqueta. Requiere exactamente uno de subject, key o keyPrefix:

// Baja del usuario: cancela todos sus recordatorios pendientes
const { cancelled, raced } = await ctx.jelou.cancelDefer({
  subject: `user_${input.userId}`,
});

ctx.log("baja procesada", { cancelados: cancelled.length, en_curso: raced.length });

raced contiene las ejecuciones que ya se estaban disparando cuando llegó la cancelación — para esas, la verificación con ctx.guard en el handler es la última defensa. Escribe tus handlers para que sean idempotentes. Antes de una cancelación amplia, previsualiza el alcance con dryRun:

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

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

No existe “reprogramar”: una reserva es inmutable. Para cambiar la hora, cancela y agenda de nuevo.

Prueba local

schedule, scheduleAt, findDeferred y cancelDefer funcionan solo en una función desplegada. En local lanzan un error porque no hay credenciales de plataforma. Para probar el flujo con jelou functions dev, activa la simulación:

JELOU_FN_DEFER_DEV=1 jelou functions dev

En ese modo se validan los argumentos, se registra la reserva en los logs y se devuelve un resultado sintético — tu handler sigue ejecutándose, pero no se agenda nada real. Para tests unitarios usa createMockContext, cuyo ctx.jelou registra las llamadas sin red ni configuración.

Inspeccionar desde el CLI

# Reservas activas de la función del proyecto actual
jelou functions defer list

# Las que fallaron
jelou functions defer list mi-funcion --status failed

# Las de un usuario
jelou functions defer list mi-funcion --subject user_42

# Detalle de una reserva (incluye el último error)
jelou functions defer get dinv_01ksqbvyqpe0prt91exc97mh4n

Ver la referencia del CLI.

Límites

Límite	Valor
Reservas activas por empresa	1,000
Anticipación máxima	30 días
Tamaño del `payload`	64 KB
Cancelación en bloque por llamada	10,000 coincidencias

Las reservas ya disparadas, canceladas o fallidas no cuentan contra el límite de activas.

Problemas comunes

No se disparó
Se envió aunque cancelé
Error en local
Se agendó dos veces

Consulta el estado y el último error de la reserva:

jelou functions defer get dinv_01ksqbvy... --payload

Si el estado es failed, el campo de error indica por qué falló la entrega. Si es cancelled, algo la canceló antes — revisa tus llamadas a cancelDefer.

Una cancelación que llega cuando la ejecución ya empezó no la detiene. Aparece en raced y tu handler se ejecuta.Por eso la verificación va en el handler, no solo en la cancelación:

return ctx.guard
  .when("sigueActivo", async () => await usuarioActivo(input.userId))
  .run(async () => { /* envío */ });

scheduleAt unavailable: platform credentials missing

Estás llamando a la familia schedule en local. Arranca el servidor con JELOU_FN_DEFER_DEV=1 jelou functions dev para simular las reservas.

El servicio que llama a tu función reintentó. Agrega idempotencyKey (o la cabecera Idempotency-Key) con un valor derivado del evento:

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

Cron

Tareas recurrentes en horario fijo.

Mensajería

Enviar WhatsApp y validar plantillas.

Webhooks

Verificar firmas de servicios externos.

CLI

Comandos defer list y defer get.

Empezando

Desarrollador

Jelou CLI

Mensajería Outbound

Gestión

Marketplace

Canales

Configuración

Facturación

Agendar desde el handler

Parámetros

Momento absoluto

Evitar duplicados

Agendar desde una petición HTTP

Recibir el disparo

Verificar antes de actuar

Consultar lo agendado

Cancelar

Prueba local

Inspeccionar desde el CLI

Límites

Problemas comunes

Cron

Mensajería

Webhooks

CLI

​Agendar desde el handler

​Parámetros

​Momento absoluto

​Evitar duplicados

​Agendar desde una petición HTTP

​Recibir el disparo

​Verificar antes de actuar

​Consultar lo agendado

​Cancelar

​Prueba local

​Inspeccionar desde el CLI

​Límites

​Problemas comunes

Cron

Mensajería

Webhooks

CLI

Agendar desde el handler

Parámetros

Momento absoluto

Evitar duplicados

Agendar desde una petición HTTP

Recibir el disparo

Verificar antes de actuar

Consultar lo agendado

Cancelar

Prueba local

Inspeccionar desde el CLI

Límites

Problemas comunes