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. 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 deduplicate 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