Scheduling Bots Best Practices

Types of bots

Recall supports two different types of bots: scheduled and ad-hoc

Scheduled bots

📘

Scheduled bots always join on-time and will never encounter 507 errors

A scheduled bot is a bot created via the Create Bot or Schedule Bot For Calendar Event endpoints with a join_at set more than 10 minutes from the time you make the request.

You should try using scheduled bots wherever possible because:

• Scheduled bots guarantee your bots join the meeting on time every time
• Scheduled bots will never run into a 507 error (no more ad-hoc bots in the ad-hoc bot pool claim)
• Scheduled bots come at no extra charge and reserves a dedicated instance, separate from the ad-hoc bot pool (described below)

Updating scheduled bots

• The bot's original join_at is more than 10 minutes from the current time - You can update all properties on the bot using the Update Scheduled Bot endpoint.
  • If setting a new join_at, the new join_at needs to be more than 10 minutes from the current time. If the new join_at is less than 10 minutes from the current time, you will then need to delete the scheduled bot and create a new bot instead.
• The bot's original join_at is less than 10 minutes from the current time - You can update all properties using the Update Scheduled Bot endpoint.
• Once the bot starts joining the call - You cannot update the bot

Deleting scheduled bots

• More than 10 minutes before the bot's join_at - You must call the Delete Scheduled Bot endpoint.
• Less than 10 minutes before the bot's join_at - You must call the Remove Bot From Call endpoint.
• Once the bot starts joining the call - You must call the Remove Bot From Call endpoint.

Ad-hoc bots

📘

When to use ad-hoc bots

Ad-hoc bots are meant to fill in the gaps where you can't schedule bots more than 10 minutes in advance (e.g. ad-hoc/last minute meetings).

You should use ad-hoc bots sparingly, opting for scheduled bots whenever possible

An ad-hoc bot is a bot created via the Create Bot or Schedule Bot For Calendar Event endpoints with a join_at set less than 10 minutes from the time you make the request.

Updating ad-hoc bots

• Less than 10 minutes before the bot's join_at - You can update all properties except the join_at field using the Update Scheduled Bot endpoint
• Once the bot starts joining the call - You cannot update the bot

Deleting ad-hoc bots

• Less than 10 minutes before the bot's join_at - You must call the Remove Bot From Call endpoint.
• Once the bot starts joining the call - You must call the Remove Bot From Call endpoint.

Ad-hoc bot pool

Starting up a bot takes some time (10 minutes) before it is ready to join a meeting since each bot runs on its own dedicated machine. Because of this, we maintain a pool of "warm" bot instances that are already running in cases where you need to claim a bot last minute (or ad-hoc)

Each region has its own dedicated ad-hoc bot pool and this ad-hoc bot pool is shared among all developers in a region. The ad-hoc bot pool is adaptive, constantly being replenished and grows with active usage.

That said, the bot pool can still be drained during short periods with very high ad-hoc bot activity in a specific region. In these cases, there are no warm bot instances available and you will need to wait until more bot instances have warmed up before you can claim an ad-hoc bot

❗️

507 error: the limitation of ad-hoc bots

If you rely on ad-hoc bots, you will eventually encounter 507 errors indicating there are no more ad-hoc bots left to claim.

When you encounter a 507 error, you can:

• Retry the request every 30s until you're able to claim an ad-hoc (usually within a few retries).
• Audit your workflows to see if you can use scheduled bots which never encounter 507 errors

Best Practices

Use scheduled bots over ad-hoc bots when possible

To create a scheduled bot, set a join_at in the Create Bot request config indicating the time the bot should join a call:

curl -X POST https://$RECALLAI_REGION.recall.ai/api/v1/bot \
    -H 'Authorization: Token $RECALLAI_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '
    {
      "join_at": "TIME_TO_JOIN_CALL", // ISO8601 datetime (e.g. "2030-01-01 00:00:00"
      "meeting_url": "$MEETING_URL",
      "bot_name": "My Bot",
      "recording_config": {"transcript": {"provider": {"meeting_captions": {}}}}
    }'

📘

Setting a join_at now or in the past will deploy an ad-hoc bot