Once you've successfully created a calendar in Recall, you can start scheduling bots to calendar events for the same using the below steps:

1. Sync Events

Once a calendar is connected, you will start receiving calendar sync events webhooks whenever an event is added/updated/removed for the calendar.

For each web-hook, you should fetch the list of updated calendar events via List Calendar Events by setting the updated_at__gte parameter as the last_updated_ts value from the webhook payload.

Use the is_deleted field on the calendar event object to know if the event has been removed from the calendar or not. Recall does not delete any calendar events to have a consistent trail of record. If you're listing calendar events to show them to your users, you should filter out deleted events by setting is_deleted to false.

📘
Upon the initial connection of a calendar, you can still rely on the above fetching logic to fetch all events on the newly-connected calendar, as the last_updated_ts in the initial calendar.sync_events webhook will match the updated_at on the calendar's newly-populated events.

Note that created/deleted/updated events returned by List Calendar Events will only reflect events within 1 day prior and 28 days into the future. For more info on this, see here .

2. Determine whether an event should be recorded

Once you fetch any updated calendar events by handling the calendar.sync_events webhook, you'll want to determine whether or not a bot should be scheduled for the event.

Since Calendar V2 allows you to fully control the scheduling logic, you'll want to look at the calendar data itself to determine whether or not a bot should be scheduled.

You can use the raw data of the calendar event in combination with your application's business logic (e.g recording preferences of a user) to determine this. Some common examples of this include:

Record external events Use the raw data to extract list of attendees and check those against the email of the connected calendar.
Record confirmed events Use the raw data to extract the response of the connected calendar email
Record all recurring instances of an event Store the ical_uid of the recurring instance as recording preference of the user. For each event compare the ical_uid with the stored value to decide recording status.

For detailed schemas on the raw field, see Calendar Event Platform Data.

3. Add/Remove bot from the event

Based on the recording status of the calendar event, you should make a request either to the Schedule Bot for Calendar Event or Remove Bot From Calendar Event endpoint.

For the case where a bot is already scheduled for the event, but the event's time was updated, you should call the Schedule Bot for Calendar Event endpoint - you do not need to explicitly delete the previously-scheduled bot, as Recall's deduplication mechanism will automatically override it with the newly-created bot.

The response object will contain the updated calendar event. The bots field will contain reference to bots(if any) that are scheduled to join the calendar event along with relevant metadata (deduplication_key, start_time, meeting_url).

Add Bot

Use deduplication_key to share bots across multiple calendar events. More on this in de-duplicating bots section below.
Use bot_config to specify the configuration for the bot. Incase multiple requests are made for the same calendar event, the config supplied in most recent request will get applied to the bot. For each request, include complete bot_config required (this endpoint does not support partial updates). This allows you to have custom bot configuration based on the calendar event.
Possible error messages returned by the API when calling the Schedule Bot For Calendar Event endpoint:

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"non_field_errors":["Cannot schedule bot as calendar is not connected."]}} // Calendar is in the disconnected state

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"non_field_errors":["Cannot schedule bot as calendar event has ended."]}} // Calendar event end time has already passed

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"non_field_errors":["Cannot schedule bot as calendar event is cancelled."]}} // Calendar event has been removed from the user's calendar

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"non_field_errors":["Cannot schedule bot as calendar event does not have valid meeting url."]}} // Meeting URL is missing from calendar event or bot_config

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"non_field_errors":["Invalid bot_config. It should be an object."]}} // bot_config is not an object (e.g. of a valid format: `{ "bot_name": "notetaker" }`

{"code":"invalid_request_data","message":"Unable to process request because invalid data was submitted. Check `errors` field for more details.","errors":{"join_at":["'{YOUR_JOIN_AT_FIELD}' is not a valid ISO8601 datetime string."]}} //  join_at is not a valid ISO8601 datetime string. (e.g. of a valid format: 2025-01-30 00:00:00)

Remove Bot
- Removes the link between the scheduled bot and the calendar event.
- The bot is deleted only after the Delete Scheduled Bot for Calendar Event endpoint has been called for all calendar events linked to the bot (as a result of de-duplication)
- For example:
  - If a bot is linked with just one calendar event (no deduplication), calling the Delete Scheduled Bot for Calendar Event for that calendar event will remove the link and delete the bot, as no other events are linked to it
  - If a bot is linked to multiple calendar events (as a result of de-duplication), calling the Delete Scheduled Bot for Calendar Event for that calendar event will remove the link for the bot, but the bot will still show up to the meeting on behalf of the other calendar events it is linked to

📘
Deleted events
Bots are automatically removed when a calendar event is deleted (removed from the user's calendar).

4. Deduplicating Bots: Custom Bot Deduplication Key

Deduplication allows you to share a bot across multiple calendar events. This is useful in cases where multiple connected calendars have a shared event marked for recording and you want to avoid scheduling multiple bots(1 bot for each calendar).

The deduplication_key(*required field) allows you to create this grouping on your end. Some common use cases with recommended value for deduplication_key are listed below

Deduplicate All (Recommended) In this case you can set the deduplication_key to be {event.start_time}-{event.meeting_url}. It will ensure only 1 bot is scheduled across all connected calendars(for your Recall account)
Deduplicate by event and attendee's email domain In this case you set deduplication_key to be {event.start_time}-{event.meeting_url}-{calendar_email_domain}. It will ensure 1 bot per unique company domain across all connected calendars(for your Recall account) is scheduled.
No Deduplication You can set the deduplication_key to be {event.start_time}-{event.meeting_url}-{event.id}. It will schedule 1 bot per connected calendar for a shared event.

Important:

The logic for generating the deduplication_key should remain consistent for all events. Failure to do so can result in unexpected scheduling behaviour. Incase you want to switch the de-duplication scheme from one to another, we recommend deleting all connected calendars and re-creating them.
Deduplication keys only apply to future-scheduled bots. This means if you send a bot to a call, kick that bot, and schedule another bot for that event using the same deduplication key, this new bot will not be deduplicated.
Deduplication keys are scoped to a given workspace. This means that if multiple workspaces use the same deduplication key for a calendar event, this will result in multiple bots joining.
The deduplication key is only used when deciding whether to reuse an existing bot or create a new one while linking calendar events to bots. This means that changing the deduplication key may not generate a new bot id - for example, a new bot id won't be generated if the bot only has one calendar event linked to it

In your case, because this bot is already linked to just this one calendar event and there are no other events involved, changing the deduplication key on the same event will not create a new bot

Scheduling Caveats

While the above scheduling should work in most of the cases, you can run into unexpected values/responses from the API. Some of these are listed below for reference

Perpetual Event

In some cases a single calendar event is re-used by the user by moving the same event forward on their calendar after the meeting ends.

In this case, the bots field on the calendar event can contain multiple entries, 1 for each recorded occurrence of the event.

Pre-poned Event

A calendar event that is marked for recording in the future can get preponed to start in near future (<5m) from now. In such cases the response for Add Bot endpoint can return with a 507, this is due to not enough bots being available in the ad-hoc bot pool(the originally scheduled bot cannot be used in such cases as it's not ready to join the call in the updated time). We recommend, you retry the Add Bot endpoint request in such cases.

Updating Scheduled Bots

To make updates to a bot scheduled with the calendar v2 integration, you must use the Schedule Bot For Calendar Event endpoint to update the bot config. Updates made with the Update Scheduled Bot may not take effect as updates to the calendar event by the user could overwrite your Update Scheduled Bot request.

If a bot is updated too close to the start of a calendar event, the bot may already be initialized and any changes made will not be applied.

We recommend making any changes at least 10 minutes before the start of the event to ensure any changes are applied accordingly.

Handling 409s

If multiple requests for adding/removing bot from a calendar event (with same deduplication_key) are dispatched in parallel, you may receive 409 response status code for a sub-set of these. We recommend retrying these with a backoff on your end.

Disconnecting/Deleting a calendar

When a user wants to disconnect their calendar, there are two ways they can do this:

Deleting their calendar from Recall.
Removing the OAuth connection from their Connected Apps on their Google/Microsoft account.

Deleting their calendar from Recall (recommended)

We highly recommend having a button or other trigger in your app that allows users to disconnect their calendar.

When they trigger this, you should call Delete Calendar using their calendar ID, which will immediately clean up bots scheduled to their calendar.

Removing the OAuth connection from their Google/Microsoft account

When a user removes your OAuth connection directly from their Google/Microsoft installed apps, bots will also be unscheduled from their calendar events.

However, Recall does not get notified when a user disconnects their calendar in this way, and so there can be a delay of up to a few hours before Recall is aware that they revoked their permission. This can lead to a delay in unscheduling any bots.

For this reason, we highly recommend allowing users to delete their calendars from your app directly, which will clean up any scheduled bots immediately.

Handling rate limits

Both the Schedule Bot For Calendar Event and Delete Bot From Calendar Event endpoints have their own respective rate limits (seen in the links above). Incase you are observing rate limit errors (returned as Status Code: 429) please review your integration to ensure

Requests for events that are in the past are not being triggered (e.g triggering Delete Bot From Calendar Event for events that have already ended)
Request for events in the future are triggered in chronological order(this ensures most recent event schedules are updated first)

If you are experiencing rate limits issues even post these, please reach out to us for further assistance.

FAQs

When calling Delete endpoint for a calendar, will bots scheduled for meetings associated with that calendar be automatically deleted ?

The calendar delete operation ensures bots that are scheduled for all future meetings associated with the calendar will automatically get cleaned up. The API consumer does not need to explicitly unschedule bots before deleting the calendar

The bot join time does not update if the calendar event’s time is changed. How should this be handled ?

You will receive calendar sync events webhook whenever an event is updated for a calendar. This update can be change of one or more attributes of the calendar event e.g start time, attendees, meeting url etc. For each of these webhook(s), you should re-fetch the calendar event and follow the below steps

Figure out if event should be recorded based on updated data. https://recallai.readme.io/reference/scheduling-guide#2-figure-out-recording-status-of-an-event
Trigger Add/Remove bot endpoint to update the bot schedule for the event. https://recallai.readme.io/reference/scheduling-guide#3-addremove-bot-from-the-event

Recall does not automatically update the bot on changes to start time as this case will automatically be handled in the above implementation and ensures you add/remove bots using the latest event data on your end. For e.g consider the below case

Your application business logic requires not recording calls if attendees in an event do not belong to external domains.
A connected calendar C1 has event E1 which has external attendees and has a bot scheduled to record it.
Now E1 gets updated with a new start time and external attendees have been removed from it.
Your business logic requires the bot to be unscheduled, however Recall cannot derive this on it's own looking at the raw calendar data, thus automatically re-scheduling the bot(by Recall) to new start time would not be desirable.

The API only returns events from user's primary calendar. Does Recall support fetching events from other calendars the user has access to ?

The calendar integration only supports fetching events from the user's primary calendar at the moment. Please reach out to the team if you require support for accessing events on other calendars.

How does the time window of events returned from Recall work?

Recall will fire a calendar.sync_events webhook whenever a change to the calendar's events is made.

However, the window in which calendar events are synced to Recall, and thus, will be displayed in any updated_at__gte queries to List Calendar Events, is as follows:

Future events: 28 days

If events are scheduled outside of the 28 days, we will send a webhook as soon as the event enters the 28 day window. This ensures you don't miss any current or future events

For example, if a user makes a change to a calendar event 28 days in the future, this event will not appear when calling List Calendar Events. When the event is within 28 days from the current time, the event will appear in List Calendar Events and you will receive a webhook notification about the event

Since bots need not be scheduled outside of this window, Recall only stores and updates events within this sliding time window. If your app requires you to fetch events outside of this window, for example, to display events in your UI, then you can use the underlying OAuth token for the calendar and fetch these directly from the meeting provider as needed.

How can I make my bots scheduled for a calendar event join on time?

You can overwrite the bot_config.join_at timestamp when calling the Schedule Bot For Calendar Event api to make the bot join a few minutes early

How will I know if a bot is unscheduled for a calendar event?

There are several ways a calendar v2 bot can be unscheduled:

You explicitly call the Delete Scheduled Bot For Calendar Event endpoint - the bot will be removed for the given calendar event
The calendar event has been removed from the user's calendar - you will receive a calendar.sync_events webhook, and one of the updated calendar events will include an is_deleted: true field. This indicates the event was removed, so the bot won't join this user's calls
The calendar has been disconnected. You will receive a calendar.update webhook when a calendar is disconnected. All bots for this calendar will be removed.

Note: For deduplicated bots shared by multiple users, only the association for the disconnected user's calendar will be removed. The bot will remain active for other users until all associations are removed.