botserver/docs/SET_SCHEDULE.md

SET SCHEDULE Keyword Reference

Documentation for scheduling scripts and automations in General Bots

Overview

SET SCHEDULE has two distinct usages:

1. File-level scheduler: When placed at the top of a .bas file, defines when the script runs automatically
2. Runtime scheduling: When used within code, schedules another script to run at a specific time

Usage 1: File-Level Scheduler

When SET SCHEDULE appears at the top of a file (before any executable code), it registers the entire script to run on a cron schedule.

Syntax

SET SCHEDULE "cron_expression"

' Rest of script follows
TALK "This runs on schedule"

Examples

' Run every day at 9 AM
SET SCHEDULE "0 9 * * *"

TALK "Good morning! Running daily report..."
stats = AGGREGATE "sales", "SUM", "amount", "date = TODAY()"
SEND TEMPLATE "daily-report", "email", "team@company.com", #{total: stats}

' Run every Monday at 10 AM
SET SCHEDULE "0 10 * * 1"

TALK "Weekly summary starting..."
' Generate weekly report

' Run first day of every month at midnight
SET SCHEDULE "0 0 1 * *"

TALK "Monthly billing cycle..."
' Process monthly billing

Cron Expression Reference

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Expression	Description
0 9 * * *	Every day at 9:00 AM
0 9 * * 1-5	Weekdays at 9:00 AM
0 */2 * * *	Every 2 hours
30 8 * * 1	Mondays at 8:30 AM
0 0 1 * *	First of each month at midnight
0 12 * * 0	Sundays at noon
*/15 * * * *	Every 15 minutes
0 9,17 * * *	At 9 AM and 5 PM daily

Usage 2: Runtime Scheduling

When used within code (not at file top), schedules another script to run at a specified time.

Syntax

' Schedule with cron + date
SET SCHEDULE "cron_expression" date, "script.bas"

' Schedule for specific date/time
SET SCHEDULE datetime, "script.bas"

Examples

' Schedule script to run in 3 days at 9 AM
SET SCHEDULE "0 9 * * *" DATEADD(TODAY(), 3, "day"), "followup-email.bas"

' Schedule for specific datetime
SET SCHEDULE "2025-02-15 10:00", "product-launch.bas"

' Schedule relative to now
SET SCHEDULE DATEADD(NOW(), 1, "hour"), "reminder.bas"
SET SCHEDULE DATEADD(NOW(), 30, "minute"), "check-status.bas"

' Campaign scheduling example
ON FORM SUBMIT "signup"
    ' Welcome email immediately
    SEND TEMPLATE "welcome", "email", fields.email, #{name: fields.name}
    
    ' Schedule follow-up sequence
    SET SCHEDULE DATEADD(NOW(), 2, "day"), "nurture-day-2.bas"
    SET SCHEDULE DATEADD(NOW(), 5, "day"), "nurture-day-5.bas"
    SET SCHEDULE DATEADD(NOW(), 14, "day"), "nurture-day-14.bas"
END ON

Passing Data to Scheduled Scripts

Use SET BOT MEMORY to pass data to scheduled scripts:

' In the scheduling script
SET BOT MEMORY "scheduled_lead_" + lead_id, lead_email
SET SCHEDULE DATEADD(NOW(), 7, "day"), "followup.bas"

' In followup.bas
PARAM lead_id AS string
lead_email = GET BOT MEMORY "scheduled_lead_" + lead_id
SEND TEMPLATE "followup", "email", lead_email, #{id: lead_id}

Campaign Drip Sequence Example

' welcome-sequence.bas - File-level scheduler not used here
' This is triggered by form submission

PARAM email AS string
PARAM name AS string

DESCRIPTION "Start welcome email sequence"

' Day 0: Immediate welcome
WITH vars
    .name = name
    .date = TODAY()
END WITH

SEND TEMPLATE "welcome-1", "email", email, vars

' Store lead info for scheduled scripts
SET BOT MEMORY "welcome_" + email + "_name", name

' Schedule remaining emails
SET SCHEDULE DATEADD(NOW(), 2, "day"), "welcome-day-2.bas"
SET SCHEDULE DATEADD(NOW(), 5, "day"), "welcome-day-5.bas"
SET SCHEDULE DATEADD(NOW(), 7, "day"), "welcome-day-7.bas"

TALK "Welcome sequence started for " + email

Daily Report Example

' daily-sales-report.bas
SET SCHEDULE "0 18 * * 1-5"

' This runs every weekday at 6 PM

today_sales = AGGREGATE "orders", "SUM", "total", "date = TODAY()"
order_count = AGGREGATE "orders", "COUNT", "id", "date = TODAY()"
avg_order = IIF(order_count > 0, today_sales / order_count, 0)

WITH report
    .date = TODAY()
    .total_sales = today_sales
    .order_count = order_count
    .average_order = ROUND(avg_order, 2)
END WITH

SEND TEMPLATE "daily-sales", "email", "sales@company.com", report

TALK "Daily report sent: $" + today_sales

Canceling Scheduled Tasks

Scheduled tasks are stored in system_automations table. To cancel:

' Remove scheduled automation
DELETE "system_automations", "param = 'followup.bas' AND bot_id = '" + bot_id + "'"

Best Practices

1. Use descriptive script names: welcome-day-2.bas not email2.bas
2. Store context in BOT MEMORY: Pass lead ID, not entire objects
3. Check for unsubscribes: Before sending scheduled emails
4. Handle errors gracefully: Scheduled scripts should not crash
5. Log execution: Track when scheduled scripts run
6. Use appropriate times: Consider timezone and recipient preferences
7. Avoid overlapping schedules: Don't schedule too many scripts at same time

Database Schema

Scheduled tasks are stored in system_automations:

Column	Type	Description
id	UUID	Automation ID
bot_id	UUID	Bot owner
kind	INT	Trigger type (Scheduled = 1)
schedule	TEXT	Cron expression
param	TEXT	Script filename
is_active	BOOL	Active status
last_triggered	TIMESTAMP	Last execution time

Comparison

Feature	File-Level	Runtime
Location	Top of file	Anywhere in code
Purpose	Recurring execution	One-time scheduling
Timing	Cron-based recurring	Specific date/time
Script	Self (current file)	Other script
Use case	Reports, cleanup	Drip campaigns, reminders