GuidesAPI Reference

Scheduled Bots

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

Why Use Scheduled Bots?Copied!

  • Ensure 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.
  • Avoid having to writing your own job scheduler for launching bots: We handle the scheduling for you
  • Integrate with calendar systems: Perfect for joining meetings at scheduled calendar event times

Creating a Scheduled BotCopied!

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 fieldCopied!

  • 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 LifecycleCopied!

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

1. Scheduled StateCopied!

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

2. Staged StateCopied!

  • When: Resources have been allocated and the bot is ready to join
  • What happens: The bot resources are allocated and the bot is waiting for the exact join time
  • Duration: Until the join_at time

3. Joining StateCopied!

  • When: At the specified join_at time
  • What happens: The bot actively attempts to join the meeting
  • Duration: Until the bot successfully joins or encounters an error

4. Subsequent StatesCopied!

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

Managing Scheduled BotsCopied!

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

Rescheduling a Scheduled BotCopied!

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 BotCopied!

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