Scheduling Guide

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 has 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 (re)fetch the calendar events via List Calendar Events. You can choose to do either a full sync or use the last_updated_ts field in the payload (pass as updated_at__gte query parameter) to do an incremental sync(recommended).

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, and the consumer is expected to filter out events on basis of is_deleted attribute when syncing/displaying them to the end user.

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. Figure out recording status of an event

After events have been synced, for each calendar event, you should decide whether it needs to be recorded. 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 decide the same. Some examples below for reference are

1. Record external events
   Use the raw data to extract list of attendees and check those against the email of the connected calendar.
2. Record confirmed events
   Use the raw data to extract the response of the connected calendar email
3. 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.

3. Add/Remove bot from the event

Based on the recording status of the calendar event, you should send request to either Add Bot or Remove Bot endpoint. 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).

1. 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.
2. Remove Bot
   • Delete scheduled bot for this event. The bot will only get deleted if it is not shared by any other calendar event(as a result of de-duplication).

📘

Deleted events

Bots are automatically removed when a calendar event is deleted.

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

• No Deduplication
  This is the simple case where you can set the deduplication_key to be {event.id}. It will schedule 1 bot per connected calendar for a shared event.
• 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.

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 are workspace-scoped

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.

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 it forward in the timeline after a specific occurrence. When recording such events, the bots field 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.

Disconnecting/Deleting a calendar

When a calendar gets disconnected(due to revoked permissions/via API) or deleted, Recall will automatically clean up all future scheduled bots for events on the same. This also applies to any events that were marked for recording but are cancelled.

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

1. 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
2. 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:

• Past events: 1 day
• Future events: 28 days

For example, if a user makes a change to a calendar event further than 1 day in the past, or 28 days in the future, this event will not appear when calling List Calendar Events.

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.