Integration Guide

1. Initial setup

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

2. Setup OAuth Clients for Providers

Setup OAuth Providers for the calendar platforms you are planning to support.

• 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 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)
• webhook_url: Web hooks related to this specific calendar will be sent to this URL.

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. Process Web hooks

Once a calendar has been created you should start receiving web hooks related to updates for it on the webhook_url. Refer to this guide on the type and how to handle each web hook.

6. Fetch Calendar Events

You can use the List Calendar Events to fetch the list of events for a specific calendar.

7. Schedule bots to calendar events

There are a couple of options here:

Recall Managed Scheduling (Recommended)

Use Recall's scheduling endpoints to add/remove bots from calendar events with deduplication support. Please refer to the Scheduling Guide for more details.

Self Managed Scheduling

With this option the API consumers can use the existing Create Bot & Delete Bot endpoints in combination with meeting_url & start_time values from a calendar event to add/remove bots to calendar events. This means the API consumer is responsible for managing the relationship b/w bots and calendar events completely on their end and handles cases such as de-duplication, event re-schedule/delete etc.