Skip to main content

Scheduled & Broadcast

Cron flows, reminders, and pushing messages to your whole audience.

Cron flows​

A schedule trigger runs on a cron expression. Remember: scheduled flows have no chat in scope, so send to an explicit chat_id — usually one you captured earlier into a shared.* variable.

shared group_chat_id: Number = 0

flow setup on command "/setup" {
  set { shared.group_chat_id = user.chat.id }
  send.text("✅ This chat will receive scheduled posts.")
}

flow morning on schedule "0 9 * * *" {
  when shared.group_chat_id != 0 {
    send.text("☀️ Good morning, everyone!", chat_id: shared.group_chat_id)
  }
}

Weekly leaderboard + reset​

A classic pattern (from the karma and quiz blueprints): every Monday at 09:00, post the leaderboard, then zero the weekly counters. Since you can't mutate array elements in place, rebuild the array.

flow weekly on schedule "0 9 * * 1" {
  when shared.group_chat_id != 0 {
    set { flow.ranked = array.slice(array.sortBy(shared.ledger, "rep", true), 0, 10) }
    when util.len(flow.ranked) > 0 {
      set { flow.body = "🏆 Weekly Leaderboard\n\n" }
      foreach e, i in flow.ranked {
        set { flow.pos = i + 1 }
        set { flow.body = flow.body + `${flow.pos}. ${e.name} — ${e.rep}\n` }
      }
      send.text(flow.body, chat_id: shared.group_chat_id)
    }
    // Reset weekly counters (rep + totals preserved).
    set { flow.fresh = [] }
    foreach e in shared.ledger {
      set { flow.fresh << [{ uid: e.uid, name: e.name, rep: e.rep, weekly_msgs: 0, total_msgs: e.total_msgs }] }
    }
    set { shared.ledger = flow.fresh }
  }
}

Reminders​

Schedule a one-off reminder with schedule.create, and cancel it if it's no longer needed:

flow remind_me on command "/remind" {
  let { task_id } = schedule.create(
    trigger_name: "fire_reminder",
    params: { delay: "1h" },
    user_id: user.id
  )
  set { user.reminder_task = task_id }
  send.text("⏰ I'll remind you in 1 hour.")
}

flow fire_reminder on schedule "0 0 * * *" {
  // (Triggered by schedule.create; sends the reminder.)
  send.text("⏰ Reminder!", chat_id: user.id)
}

For per-user reminders driven by data (like a task manager DMing due tasks), run a frequent cron that scans a shared.* list of subscribers and DMs the ones that are due — a scheduled flow can read shared.* but not other users' user.*, so keep the data it needs in shared.*.

Broadcasting to your audience​

To send the same message to everyone, use the broadcast recipes — they pace delivery to respect Telegram's rate limits:

flow announce on command "/announce" {
  when user.id != global.admin_id {
    send.text("🚫 Admins only.")
    stop
  }
  telegram.broadcastMessage(text: "📢 New feature just shipped — check /whatsnew!")
  send.text("✅ Broadcast queued.")
}

Other broadcast recipes: telegram.broadcastMedia (a photo/video/document) and telegram.broadcastFlow (run a subflow per user). See Recipes. Under the hood these use the jobs.* family (Scheduling & jobs).

See also​