Scheduler & Cron Jobs

Schedule tasks to run at specific times or on recurring schedules. Perfect for reminders, daily digests, follow-ups, and automated workflows.

---

Overview

BotGami's scheduler system lets you:

• 📅 Schedule one-time tasks — Run after a delay or at a specific time
• 🔄 Create recurring jobs — Use cron expressions for repeating schedules
• ⏰ Send reminders — Schedule messages for users
• ❌ Cancel scheduled tasks — Stop pending tasks before they run

---

Quick Start: Schedule a Reminder

Let's create a simple reminder bot:

Step 1: Create a command to set a reminder

1. Add Command Trigger for /remind
2. Add Ask node: "In how many minutes?"
3. Add flow.schedule node:
   • Mode: delay
   • Trigger Name: reminder
4. Connect DelayMs input to: answer * 60000 (minutes to ms)
5. Add Send Message: "I'll remind you in {{answer}} minutes!"

Step 2: Create the reminder trigger

1. Add Scheduled Trigger with name reminder
2. Add Send Message: "⏰ Here's your reminder!"

---

Scheduler Nodes

sys.cron_trigger — Recurring Schedules

Fires automatically based on a cron schedule. Runs at the bot level (not per-user).

Configuration:

• Name — Unique identifier for this cron job (e.g., daily_digest)
• Expression — Cron expression (e.g., 0 9 * * *)
• Timezone — IANA Timezone string (e.g., America/New_York or UTC). Defaults to UTC if empty.

Outputs:

• TriggerTime — When the trigger fired
• Params — Any parameters passed

┌────────────────────┐
│  sys.cron_trigger  │──▶ NEXT
│  "0 9 * * *"       │──▶ TriggerTime
│  "daily_digest"    │
└────────────────────┘

---

sys.scheduled_trigger — Receive Scheduled Tasks

Fires when a task scheduled by flow.schedule executes.

Configuration:

• Name — Must match the trigger name used in flow.schedule

Outputs:

• Params — Data passed during scheduling
• TaskID — Task identifier
• UserID — Target user (if specified)
• TriggerTime — Execution time

┌─────────────────────┐
│ sys.scheduled_      │──▶ NEXT
│ trigger "reminder"  │──▶ Params
│                     │──▶ UserID
└─────────────────────┘

---

flow.schedule — Schedule a Task

Schedule a task from within any flow.

Configuration:

• Trigger Name — Name of the trigger to fire
• Mode — How to specify timing:
  • delay — Milliseconds from now
  • datetime — Specific date/time

Inputs:

Input	Socket	Description
DelayMs	Number	Only for delay mode. Time to wait in milliseconds.
DateTime	String	Only for datetime mode. ISO 8601 format (e.g., 2023-12-31T23:59:00Z).
Params	Object/JSON	Data passed to the sys.scheduled_trigger. accessing via Params output.
UserID	Number	Target user ID. Defaults to current user. for sys.scheduled_trigger context.
RepeatCount	Number	-1=infinite, 0=one-time (default), >0=N times.

UI Configuration

You can also set default values directly in the node's configuration panel if you don't want to use input sockets.

Outputs:

• TaskID — Use this to cancel the task later
• ScheduledFor — When the task will run

---

flow.cancel_schedule — Cancel a Task

Cancel a pending scheduled task.

Inputs:

• TaskID — The ID returned by flow.schedule

Outputs:

• Success — Task was cancelled
• NotFound — Task not found or already executed
• Cancelled — Boolean result

---

flow.schedule_message — Quick Message Scheduling

Convenience node to schedule a message without a separate trigger.

Inputs:

Input	Description
Message	Text to send
DelayMs	Delay in milliseconds
DateTime	Alternative: specific date/time
ChatID	Target chat (default: current user)

---

Cron Expression Format

Standard 5-field format: minute hour day month weekday

Field	Values	Wildcards
Minute	0-59	* = every, */5 = every 5
Hour	0-23	* = every
Day of Month	1-31	* = every
Month	1-12	* = every
Day of Week	0-6 (Sun=0)	1-5 = Mon-Fri

Common Examples

Expression	Description
0 9 * * *	Daily at 9:00 AM
0 9 * * 1-5	Weekdays at 9:00 AM
*/15 * * * *	Every 15 minutes
0 0 * * 0	Sundays at midnight
0 0 1 * *	First of each month
30 8,12,18 * * *	8:30 AM, 12:30 PM, 6:30 PM daily

---

Examples

Daily Digest

Send a summary to all users every morning:

┌────────────────────┐    ┌─────────────────┐    ┌──────────────────┐
│  sys.cron_trigger  │───▶│   Get Users     │───▶│    For Each      │
│  "0 9 * * 1-5"     │    │   (from DB)     │    │                  │
│  "daily_digest"    │    └─────────────────┘    └────────┬─────────┘
└────────────────────┘                                    │
                                                          ▼
                                              ┌──────────────────┐
                                              │   Send Message   │
                                              │   "Good morning!"│
                                              └──────────────────┘

---

Appointment Reminder

Send reminder 24 hours before:

User Books Appointment
         │
         ▼
┌─────────────────────┐
│   flow.schedule     │
│   Mode: datetime    │
│   Trigger: reminder │
│   DateTime: (apt - 24h) │
│   Params: {apt_id}  │
└─────────────────────┘
         │
         ▼ (24 hours later)
         
┌─────────────────────┐
│  sys.scheduled_     │
│  trigger "reminder" │
└─────────────────────┘
         │
         ▼
┌─────────────────────┐
│   Send Message      │
│   "Reminder: Your   │
│    appointment is   │
│    tomorrow!"       │
└─────────────────────┘

---

Follow-Up Message

Send a follow-up 1 hour after user interaction:

// After user completes a form
flow.schedule:
  Mode: delay
  DelayMs: 3600000  // 1 hour
  TriggerName: "followup"
  Params: {
    user_name: var.name,
    form_type: "survey"
  }

---

Cancellable Reminder

Let users cancel their own reminders:

Setting the reminder:

flow.schedule → Save TaskID to var.reminder_id

Canceling:

/cancel command → flow.cancel_schedule with var.reminder_id

---

Repeat Count

Control how many times a task repeats:

Value	Behavior
0	One-time only (default)
-1	Infinite (for cron)
5	Repeat 5 times, then stop

For cron expressions, RepeatCount defaults to -1 (infinite).

---

Best Practices

Use Descriptive Trigger Names

Name your triggers clearly: daily_digest, appointment_reminder, weekly_report

Store Task IDs

Always save the TaskID if users might need to cancel:

var.pending_reminder = TaskID

Mind the Timezone

Cron expressions use UTC by default. Specify timezone if needed:

Timezone: "America/New_York"

Rate Limiting

For mass notifications (daily digest to all users), add delays between messages to avoid Telegram rate limits.

---

Error Handling

If a scheduled task fails:

• Status is set to failed
• Error message is logged
• The task won't retry automatically

For critical tasks, consider:

1. Using Try-Catch in your triggered flow
2. Logging failures to admin
3. Implementing manual retry logic

---

Next Steps

• Booking System Tutorial → — Uses scheduler for reminders
• Best Practices → — Scheduling patterns