Creating and scheduling bots

Bots are single-use and each run on their own machine. To make a bot join a meeting, you must have a meeting URL and a time for the bot to join the meeting. The most common way to get this information is to:

• Use Recall.ai's Calendar Integration to easily connect and automate the bot scheduling lifecycle. If using this integration, you will can use the calendar endpoints defined in the linked guide to schedule bots.
• Use your own calendar integration to get the meeting details from the user's calendar events. You will need to use the Create Bot endpoint to create/schedule bots.

When creating bots, you should schedule the bot as soon as you receive the meeting URL and the meeting start time (e.g. when the user connects their calendar or when you're notified that a calendar event was created).

✅

Bots are meant to be scheduled to join calls more than 10 minutes in advance

Scheduled bots are created when a bot's join_at is more than 10 min in advance. Scheduled bots are guaranteed to join on-time and will never be late to meetings.

❗️

Bots joining calls with less than 10 min notice

Ad-hoc bots are created when a bot's join_at is less than 10 min in advance or omitted completely at the time you call the Create Bot endpoint. For example, users may meet spontaneously and the user will supply the meeting URL to join a live (on-demand) meeting.

Recall maintains a limited pool of warm bots called the ad-hoc bot pool (since bots take time to start up), and the pool can deplete during brief spikes in which the API will return 507 errors. We're constantly replenishing the pool so you should be able to claim a bot within a few attempts by retrying every 30s.

Ad-hoc bots are a secondary option to scheduled bots and should be used sparingly, filling in the gaps where scheduled bots can't (e.g. ad-hoc/on-demand meetings). If your use case heavily depends on ad-hoc bots, reach out to [email protected] with more details about your implementation to discuss potential options available to you.

How to schedule a bot

To schedule a bot, you only need to set the join_at field to a time that is more than 10 minutes in the future. Recall will automatically reserve and start up a machine for your bot to ensure the bot joins on time. You can create a scheduled bot using the example below:

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": "SOME_TIME_MORE_THAN_10_MIN_IN_THE_FUTURE",
      "meeting_url": "$MEETING_URL",
      "bot_name": "My Bot",
    }'

How to update a scheduled bot

Scheduled bots are editable up until they start joining the meeting. The main thing to watch is the 10-minute window around join_at.

{
"code": "update_bot_failed",
"detail": "Only non-dispatched bots can be updated"
}

{
"code": "update_bot_failed",
"detail": "Not enough time to launch new bot"
}

How to delete a scheduled bot

Cancelling depends on how close you are to join_at.

How to delete scheduled bots in bulk

To delete many scheduled bots at once, you will need to:

• Iterate over the results returned by the List Bots endpoint with join_at >= now() (you can filter for specific bots if preferred)
• Call the Delete Scheduled Bot for every bot in the results

📘

See this sample app for a script to filter and unschedule/delete many scheduled bots in bulk.

How to deduplicate bots

❗️

Deduplication is only supported with the calendar integration.

If you schedule bots directly via the Create Bot endpoint, Recall will not deduplicate bots automatically. To avoid creating multiple bots for the same meeting, you must implement deduplication in your own app (typically by persisting a meeting → bot mapping in your database). See below for details on how to manually deduplicate bots.

Deduplication allows you to schedule one bot to join a meeting on behalf of multiple participants. This is useful in cases where multiple users have a shared event marked for recording and you want to avoid scheduling multiple bots.

The Calendar Integration supports bot deduplication by default:

• Calendar V1 - only one bot joins the call among all of your calendar v1 users
• Calendar V2 - you can configure how bots are deduplicated by using deduplication keys

For bots created outside of our calendar integration using the Create Bot endpoint, Recall does not provide built-in bot deduplication and you will need to manually implement the logic to deduplicate bots in your app.

Manually deduplicating bots

At a high level, you can keep a record in your database of which meetings already have a Recall bot, and you check that record before you call Create Bot endpoint. If the meeting already has a bot, you reuse it. If it doesn’t, you create one and save the association for next time. This prevents unnecessary Create Bot requests and ensures you don’t schedule multiple bots for the same meeting.

For example, you’d have two tables in your database:

• bot_id <> dedup_key - a one-to-one mapping between your deduplication key and a Recall bot
• bot_id <> user_id - a one-to-many mapping between a bot and the users it should be associated with (so you can reuse the same bot across multiple users without creating duplicates)

This lets you implement “one bot per meeting/company/user” like this:

• When a meeting is created or updated, generate a stable dedup_key for that meeting (see here for more info on creating deduplication keys)
• Look up dedup_key in bot_id <> dedup_key table:
  • If the association exists: reuse the existing bot_id (don’t create a new bot). Then create/update the bot_id <> user_id association to ensure the bot is associated with the user/team that just scheduled it.
  • If the association doesn’t exist: create a new bot using the Create Bot endpoint, then insert the new {dedup_key, bot_id} row and create the initial bot_id <> user_id association(s)

📘

When a meeting's start_time or meeting_url is updated, don't forget to:

• Update the deduplication key for that meeting in the deduplication keys <> bots association
• Updating the bot using the Update Scheduled Bot endpoint

Deduplication keys

Some common use cases with recommended values for deduplication_key are listed below:

FAQ

What's the concurrent bot limit?

The "concurrent bot limit" refers to concurrent bots live in meetings deployed ad-hoc (referred to as ad-hoc bots). Ad-hoc bots are rare in practice because most bots should be scheduled in advance. Ad-hoc bots are only meant to fill in the gaps where scheduled bots (bots scheduled more than 10 minutes in advance) can’t (e.g., last-minute meetings).

There are no limits on concurrent bots live in meetings scheduled more than 10 minutes in advance. This effectively means that most bots won’t count toward this 30 concurrent bots limit

If you are expecting high ad-hoc bot usage, please reach out to support with details around your constraint/limitations and we can work with you to find a oslution that fits your use case.