Scheduled Actions - Thread Documentation

Scheduled Actions Overview

Scheduled actions are actions with delay_hours > 0 that execute at a future time. Thread’s scheduling system ensures actions trigger at the perfect moment without manual intervention. [SCREENSHOT: Scheduled actions in admin view] Caption: View upcoming scheduled actions across all accounts

How Scheduling Works

The Scheduling Pipeline

Milestone Starts

CSM starts a milestone → status changes to “in_progress”

Actions Scanned

Thread scans all actions in milestone for triggers

Immediate Actions

Actions with delay_hours: 0 execute immediately

Delayed Actions Scheduled

Actions with delays added to scheduled_action_executions tableCalculation:

execution_time = milestone_start_time + delay_hours

Example:

Milestone started: 2024-03-15 10:00 AM
Action delay: 48 hours
Scheduled execution: 2024-03-17 10:00 AM

Cron Job Monitors

Hourly cron job checks for actions ready to execute

Execution Triggered

When current time ≥ execution_time:

AI generates draft
Action moves to “ready” status
Appears in CSM Implementation Tab

Configuration

Setting Delays in Templates

When creating actions:

{
  trigger: {
    type: "milestone_start",
    delay_hours: 48  // 2 days
  }
}

Common delay values:

Hours	Duration	Use Cases
0	Immediate	Welcome emails, announcements
24	1 day	Follow-ups, reminders
48	2 days	Secondary actions, non-urgent requests
72	3 days	Giving customers breathing room
168	1 week	Long-lead items, reviews
720	30 days	Post-launch check-ins

[SCREENSHOT: Action configuration with delay setting] Caption: Set delay_hours when configuring action triggers

Changing Delays After Creation

CSMs can adjust delays for specific accounts:

Navigate to Implementation Tab
Find scheduled action (status: “pending”)
Click “Reschedule”
Enter new delay_hours or specific date/time
Save changes

Rescheduling only affects this specific account. Template delays remain unchanged for future accounts.

Viewing Scheduled Actions

Per-Account View

In Implementation Tab: Pending actions show:

Action label
Scheduled execution date/time
Days/hours until execution
Option to reschedule or execute immediately

[SCREENSHOT: Pending actions with countdown timers] Caption: See when each pending action will trigger

Organization-Wide View

(Admin only) Navigate to Settings → Scheduled Actions See:

All scheduled actions across accounts
Execution times
Associated accounts and milestones
Option to manually trigger or cancel

[SCREENSHOT: Organization scheduled actions dashboard] Caption: Admins can view all scheduled actions across the organization

The Cron System

How the Cron Job Works

Frequency: Runs every hour (configurable) Process:

Query scheduled_action_executions table
Filter for execution_time ≤ current_time AND status = pending
For each action:
- Generate AI draft (if applicable)
- Update action status to “ready”
- Notify CSM (optional)
- Remove from scheduled queue
Log execution results

Cron endpoint: /api/cron/execute-scheduled Security: Protected by CRON_SECRET environment variable

The cron job uses the admin client to bypass RLS. This is necessary for system-level operations but must be kept secure.

Cron Schedule

Configured in vercel.json:

{
  "crons": [
    {
      "path": "/api/cron/execute-scheduled",
      "schedule": "0 * * * *"
    }
  ]
}

Schedule format: Standard cron syntax

0 * * * * = Every hour at :00
0 */4 * * * = Every 4 hours
0 0 * * * = Daily at midnight

Timing Precision

Execution Timing Expectations

How precise is scheduling?

Same-Hour (✅)
Not Minute-Exact (❌)
Order Preserved (✅)

Actions scheduled for 2:00 PM will execute between 2:00-2:59 PMGuarantee: Within same hour as scheduled

For most use cases, hourly precision is sufficient. If you need minute-exact timing, execute actions manually at the desired time.

Common Scheduling Patterns

Onboarding Email Sequence

Day 0 (Kickoff starts):
├── Welcome Email (immediate)
└── Portal Introduction (immediate)

Day 1:
└── Pre-Kickoff Form (24hr delay)

Day 3:
└── Kickoff Meeting Reminder (72hr delay)

Day 7:
└── Week 1 Progress Update (168hr delay)

Day 14:
└── Mid-Implementation Check-in (336hr delay)

Multi-Touch Follow-Up

Action 1: Initial Email (immediate)
Action 2: Follow-up if no response (48hr delay)
Action 3: Final reminder (96hr delay)
Action 4: CSM manual outreach (manual trigger if still no response)

Post-Launch Sequence

Launch Day: Go-Live Email (immediate)
Day 1: Post-Launch Check-in (24hr delay)
Day 7: Week 1 Review (168hr delay)
Day 30: Monthly Success Review (720hr delay)
Day 90: Quarterly Business Review (2160hr delay)

Managing Scheduled Actions

Rescheduling Actions

When to reschedule:

Customer requested delay
Holiday or blackout period
Dependency not met
Customer capacity issues

How to reschedule:

Go to Implementation Tab
Find pending action
Click “Reschedule”
Choose:
- New delay_hours from milestone start
- Specific date/time
Save

[SCREENSHOT: Reschedule action modal] Caption: Adjust scheduled execution time

If you reschedule multiple related actions, maintain their relative spacing (e.g., if they were 48 hours apart, keep them 48 hours apart in new schedule).

Executing Early

When to execute early:

Customer ready before scheduled time
Blocking progress
Customer explicitly requested

How:

Navigate to pending action
Click “Execute Now”
Action immediately generates draft and moves to “ready”
Review and execute as normal

Executing early removes it from the scheduled queue. It won’t execute again at the originally scheduled time.

Canceling Scheduled Actions

When to cancel:

Action no longer needed
Replaced by different action
Customer no longer requires this

How:

Find pending action
Click “Cancel”
Confirm cancellation
Action removed from queue (can’t be undone)

Troubleshooting

”Scheduled Action Didn’t Trigger”

Problem: Past scheduled time but action still pending Possible causes:

Cron job hasn’t run yet (runs hourly)
Cron job failed (check logs)
Account or milestone was deleted
Action was manually canceled

Solutions:

Wait for next hour’s cron run
Check cron logs in Vercel
Manually execute if urgent
Contact support if persistent

”Action Triggered Too Early/Late”

Problem: Execution time doesn’t match expectations Possible causes:

Milestone start time different than expected
Action was manually rescheduled
Timezone confusion
Delay calculation error

Solutions:

Verify milestone started at expected time
Check action history for reschedules
Confirm timezone settings
Recalculate: milestone_start + delay_hours

”Multiple Actions Triggered at Once”

Problem: Several actions executed simultaneously, overwhelming customer Possible causes:

Multiple actions scheduled for same time
Milestone started late, backlog of actions triggered
Cron job backlog processed all at once

Solutions:

Stagger action delays in template (avoid same delay_hours)
If milestone delayed, reschedule future actions before starting
Space actions 24-48 hours apart minimum

Best Practices

Space Actions Out

Use 24-72 hour spacing between actions to avoid overwhelming customers

Consider Timezones

Schedule considering customer timezone (9 AM their time, not yours)

Plan for Delays

Expect customers to be slower than template estimates—add buffer

Monitor Pending Queue

Regularly review scheduled actions to catch issues early

Test Timing

Use test accounts to verify delay calculations work as expected

Document Patterns

Track which delay patterns work best for your customer segments

Advanced Scheduling

Conditional Delays

(Future feature) Adjust delays based on customer attributes:

{
  trigger: {
    type: "milestone_start",
    delay_hours: customer.segment === "enterprise" ? 72 : 24
  }
}

Use cases:

Longer delays for enterprise (more stakeholders)
Shorter delays for SMB (faster decision-making)
Industry-specific timing (healthcare compliance reviews)

Business Day Scheduling

(Future feature) Skip weekends and holidays:

{
  trigger: {
    type: "milestone_start",
    delay_hours: 48,
    business_days_only: true
  }
}

Example:

Friday 3 PM + 24 business hours = Tuesday 3 PM (not Saturday)

Next Steps

Action Execution

Learn how actions trigger and execute

AI Generation

Understand AI-powered draft creation

Template Design

Design templates with effective delays

Best Practices

Learn proven scheduling patterns

Overview

Templates

Accounts

Automation

Workflows

​Scheduled Actions Overview

​How Scheduling Works

​The Scheduling Pipeline

​Configuration

​Setting Delays in Templates

​Changing Delays After Creation

​Viewing Scheduled Actions

​Per-Account View

​Organization-Wide View

​The Cron System

​How the Cron Job Works

​Cron Schedule

​Timing Precision

​Execution Timing Expectations

​Common Scheduling Patterns

​Onboarding Email Sequence

​Multi-Touch Follow-Up

​Post-Launch Sequence

​Managing Scheduled Actions

​Rescheduling Actions

​Executing Early

​Canceling Scheduled Actions

​Troubleshooting

​”Scheduled Action Didn’t Trigger”

​”Action Triggered Too Early/Late”

​”Multiple Actions Triggered at Once”

​Best Practices

Space Actions Out

Consider Timezones

Plan for Delays

Monitor Pending Queue

Test Timing

Document Patterns

​Advanced Scheduling

​Conditional Delays

​Business Day Scheduling

​Next Steps

Action Execution

AI Generation

Template Design

Best Practices

Scheduled Actions Overview

How Scheduling Works

The Scheduling Pipeline

Configuration

Setting Delays in Templates

Changing Delays After Creation

Viewing Scheduled Actions

Per-Account View

Organization-Wide View

The Cron System

How the Cron Job Works

Cron Schedule

Timing Precision

Execution Timing Expectations

Common Scheduling Patterns

Onboarding Email Sequence

Multi-Touch Follow-Up

Post-Launch Sequence

Managing Scheduled Actions

Rescheduling Actions

Executing Early

Canceling Scheduled Actions

Troubleshooting

”Scheduled Action Didn’t Trigger”

”Action Triggered Too Early/Late”

”Multiple Actions Triggered at Once”

Best Practices

Advanced Scheduling

Conditional Delays

Business Day Scheduling

Next Steps