Skip to main content
Scheduled bots allow you to have your bot join a meeting at a specific time in the future.

​
Why Use Scheduled Bots?

Punctual joining

When creating an ad-hoc bot there is a slight delay because of the need to allocate resources. Scheduled bots join at exactly the specified time, because the resources are allocated in advance.

No job scheduler needed

Avoid having to write your own job scheduler for launching bots. We handle the scheduling for you.

Calendar integration

Perfect for joining meetings at scheduled calendar event times.

​
Creating a Scheduled Bot

To create a scheduled bot, include the join_at parameter when making your bot creation API call: 
{
  "meeting_url": "https://zoom.us/j/123456789",
  "bot_name": "My scheduled bot",
  "join_at": "2025-06-16T16:24:00+0000"
}
The response will include: 
{
  "id": "bot_HiXYgjyeWmTVOaII",
  "meeting_url": "https://meet.google.com/gvy-zzra-ktd",
  "state": "scheduled",
  "join_at": "2025-06-16T16:55:00Z"
}

​
Requirements for the join_at field

  • Cannot be in the past: The join_at time must be in the future
  • Minimum lead time: Ideally set join_at at least 2 minutes in the future to allow sufficient time to spin up the resources for the bot
  • Format: Use ISO 8601 format (e.g., 2024-01-15T10:30:00Z)

​
Bot State Lifecycle

Scheduled bots follow a different state progression than ad-hoc bots:
1

Scheduled State

When: Initial state when a bot is created with a join_at timeWhat happens: The bot is queued and waiting until it’s time to allocate resources for the botDuration: Until resources are allocated (a few minutes before join_at)
2

Staged State

When: Resources have been allocated and the bot is ready to joinWhat happens: The bot resources are allocated and the bot is waiting for the exact join timeDuration: Until the join_at time
3

Joining State

When: At the specified join_at timeWhat happens: The bot actively attempts to join the meetingDuration: Until the bot successfully joins or encounters an error
4

Subsequent States

After joining, the bot follows the normal state progression (joined, recording, etc.).

​
Managing Scheduled Bots

You can reschedule or cancel scheduled bots while they are in the scheduled state.

​
Rescheduling a Scheduled Bot

To change the join time of a scheduled bot, use the PATCH endpoint: Request: 
PATCH /bots/{bot_id}

{
  "join_at": "2025-06-16T17:00:00Z"
}
Response: 
{
  "id": "bot_HiXYgjyeWmTVOaII",
  "meeting_url": "https://meet.google.com/gvy-zzra-ktd",
  "state": "scheduled",
  "join_at": "2025-06-16T17:00:00Z"
}
Requirements:
  • Bot must be in scheduled state
  • New join_at time cannot be in the past
  • Uses the same validation rules as when creating a scheduled bot

​
Unscheduling (Deleting) a Scheduled Bot

To cancel a scheduled bot before it joins, use the DELETE endpoint: Request: 
DELETE /bots/{bot_id}
Response: 
200 OK
Requirements:
  • Bot must be in scheduled state
  • Once deleted, the bot cannot be recovered
  • This operation only works for scheduled bots that haven’t started joining yet

Build docs developers (and LLMs) love

Get started for freeTalk to us