Integration Guide

Recall's Calendar V2 integration is best suited for integrations that require the most control and configurability, with the tradeoff of handling more implementation on your side (e.g. webhooks).

If you don't require bot-level configuration, and prefer Recall handles more of the heavy lifting, you may want to use the Calendar V1 integration instead.

1. Initial setup

Create an API Key in the Recall dashboard. This will be used for API authentication.

2. Setup OAuth Clients for Calendar Providers

Setup OAuth clients for the calendar platforms you are planning to support. We have guides for each of these here:

• Google Calendar
• Microsoft Outlook

Keep note of CLIENT_ID& CLIENT_SECRET values as they will be required later to connect calendar in Recall.

3. Authorize User & Get Refresh Token

At this point you should implement the OAuth 2.0 authorization code flow in your system.

1. Redirect the user to the authorization endpoint for a specific provider.
2. Receive a callback from the provider on successful connect.
3. Use the authorization code to retrieve a refresh_token. Refer to provider specific guides below

• Google Calendar
• Microsoft Outlook

4. Create the calendar

With the above data you can now proceed to Create Calendar in Recall.

The following parameters will be needed:

• oauth_client_id: (obtained in Step 2)
• oauth_client_secret (obtained in Step 2)
• oauth_refresh_token(obtained in Step 3)
• platform (google_calendar or microsoft_outlook)

This will create a calendar in Recall which represents the primary calendar of the account that authorized the connection. Keep a hold of the id returned in the response. You can attach it to an entity that suits the business logic of your application.

📘

OAuth refresh tokens are long lived

The refresh token you provide to Recall when creating a calendar is long-lived and allows us to manage refreshing a user's OAuth token for you automatically.

A user's refresh token will only need to be updated if it's revoked by the user, which occurs in one of two cases:

• The user manually revokes permissions (e.g. in Google or Microsoft settings)
• The user changes their password and their user settings requires them to re-authenticate OAuth permissions

When a user's refresh token is revoked, the calendar will become disconnected. In this case, the user should go through the OAuth flow and you should call Update Calendar to update the refresh token accordingly.

5. Handle calendar webhooks

Once a calendar has been created you'll begin receiving webhooks whenever an update is made to the calendar or its associated calendar events.

You'll need to set up a webhook handler to process these events - see this guide on how to handle these webhooks.

Scheduling bots for calendar events

As you're handling calendar event webhooks, there are two primary endpoints you'll need to use here:

• Schedule Bot For Calendar Event
• Delete Bot From Calendar Event

In the case of an event that was rescheduled, you can simply call the Schedule Bot For Calendar Event for the event, and the previously scheduled bot will be overridden.

When a calendar event is deleted, any scheduled bots are automatically unscheduled so you do not need to delete the bot in this case.

For an in-depth guide on bot scheduling and how to deduplicate bots in the case of shared events between multiple connected calendars, please see the Scheduling Guide.

6. Fetch Calendar Events

If you'd like to fetch calendar events to display them to your users and allow them to toggle specific meetings for recording, you can use the List Calendar Events.