Skip to main content

​
Overview

This page documents all TypeScript types, interfaces, and enums used when working with calendar integrations in the Recall AI SDK.

​
Core Types

​
CalendarPlatform

type CalendarPlatform = "google_calendar" | "microsoft_outlook";
Supported calendar platforms for integration. Platforms:
  • google_calendar: Google Calendar integration
  • microsoft_outlook: Microsoft Outlook Calendar integration

​
CalendarStatus

type CalendarStatus = "connecting" | "connected" | "disconnected";
Represents the current connection status of a calendar integration. Status Values:
  • connecting: Calendar is in the process of establishing connection
  • connected: Calendar is successfully connected and syncing
  • disconnected: Calendar connection is inactive or has been terminated

​
Request Parameters

​
CreateCalendarParams

interface CreateCalendarParams {
  oauth_client_id: string;
  oauth_client_secret: string;
  oauth_refresh_token: string;
  platform: CalendarPlatform;
  oauth_email?: string;
}
Parameters for creating a new calendar integration. Properties:
  • oauth_client_id (required): OAuth 2.0 client ID from the calendar platform
  • oauth_client_secret (required): OAuth 2.0 client secret from the calendar platform
  • oauth_refresh_token (required): OAuth 2.0 refresh token for maintaining access
  • platform (required): Calendar platform type (Google Calendar or Microsoft Outlook)
  • oauth_email: Email address associated with the calendar account

​
UpdateCalendarParams

interface UpdateCalendarParams extends BaseCalendarParams, OauthParams {
  platform?: CalendarPlatform;
  oauth_email?: string;
}
Parameters for updating an existing calendar integration. Properties:
  • id (required): Calendar integration identifier (inherited from BaseCalendarParams)
  • oauth_client_id: Updated OAuth client ID
  • oauth_client_secret: Updated OAuth client secret
  • oauth_refresh_token: Updated OAuth refresh token
  • platform: Updated calendar platform
  • oauth_email: Updated email address

​
BaseCalendarParams

interface BaseCalendarParams {
  id: string;
}
Base parameters for calendar-specific operations that require only the calendar ID. Properties:
  • id: Unique identifier for the calendar integration

​
ListCalendarParams

interface ListCalendarParams {
  created_at__gte?: Date;
  cursor?: string;
  email?: string;
  platform?: CalendarPlatform;
  status?: CalendarStatus;
}
Query parameters for filtering and paginating calendar integrations. Properties:
  • created_at__gte: Filter calendars created on or after this date (greater than or equal)
  • cursor: Pagination cursor for fetching the next page of results
  • email: Filter calendars by associated email address
  • platform: Filter by calendar platform (Google Calendar or Microsoft Outlook)
  • status: Filter by connection status

​
Response Types

​
CreateCalendarResponse

interface CreateCalendarResponse extends OauthParams {
  platform: CalendarPlatform;
  oauth_email: string;
}
Response returned after creating a calendar integration. Properties:
  • platform: The calendar platform that was connected
  • oauth_email: Email address associated with the calendar
  • oauth_client_id: Client ID used (may be masked for security)
  • oauth_client_secret: Client secret used (may be masked for security)
  • oauth_refresh_token: Refresh token (may be masked for security)

​
Internal Types

​
OauthParams

interface OauthParams {
  oauth_client_id?: string;
  oauth_client_secret?: string;
  oauth_refresh_token?: string;
}
OAuth 2.0 credential parameters used internally for authentication. Properties:
  • oauth_client_id: OAuth client identifier
  • oauth_client_secret: OAuth client secret key
  • oauth_refresh_token: Token for refreshing access credentials

​
Example Usage

​
Creating a Google Calendar Integration

import { RecallAI } from '@recall-ai/sdk';
import type { CreateCalendarParams } from '@recall-ai/sdk';

const recall = new RecallAI({ apiKey: 'your-api-key' });

const params: CreateCalendarParams = {
  oauth_client_id: 'your-google-client-id',
  oauth_client_secret: 'your-google-client-secret',
  oauth_refresh_token: 'your-refresh-token',
  platform: 'google_calendar',
  oauth_email: '[email protected]'
};

const calendar = await recall.calendar.create(params);
console.log('Calendar connected:', calendar.oauth_email);

​
Creating a Microsoft Outlook Integration

import type { CreateCalendarParams } from '@recall-ai/sdk';

const params: CreateCalendarParams = {
  oauth_client_id: 'your-microsoft-client-id',
  oauth_client_secret: 'your-microsoft-client-secret',
  oauth_refresh_token: 'your-refresh-token',
  platform: 'microsoft_outlook',
  oauth_email: '[email protected]'
};

const calendar = await recall.calendar.create(params);

​
Listing Calendar Integrations

import type { ListCalendarParams, CalendarStatus } from '@recall-ai/sdk';

const filters: ListCalendarParams = {
  platform: 'google_calendar',
  status: 'connected',
  created_at__gte: new Date('2024-01-01')
};

const calendars = await recall.calendar.list(filters);
console.log(`Found ${calendars.length} connected Google Calendars`);

​
Updating a Calendar Integration

import type { UpdateCalendarParams } from '@recall-ai/sdk';

const params: UpdateCalendarParams = {
  id: 'calendar-123',
  oauth_refresh_token: 'new-refresh-token',
  oauth_email: '[email protected]'
};

const updated = await recall.calendar.update(params);

​
Filtering by Status

import type { ListCalendarParams } from '@recall-ai/sdk';

// Find all disconnected calendars that need attention
const disconnected: ListCalendarParams = {
  status: 'disconnected'
};

const needsReauth = await recall.calendar.list(disconnected);

for (const cal of needsReauth) {
  console.log(`Calendar ${cal.oauth_email} needs reauthentication`);
}

​
Filtering by Email and Platform

import type { ListCalendarParams } from '@recall-ai/sdk';

const filters: ListCalendarParams = {
  email: '[email protected]',
  platform: 'microsoft_outlook'
};

const calendars = await recall.calendar.list(filters);

​
OAuth Setup

​
Google Calendar

To obtain OAuth credentials for Google Calendar:
  1. Go to Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Calendar API
  4. Create OAuth 2.0 credentials (Web application)
  5. Configure authorized redirect URIs
  6. Obtain the client ID and client secret
  7. Use the OAuth flow to get a refresh token

​
Microsoft Outlook

To obtain OAuth credentials for Microsoft Outlook:
  1. Go to Azure Portal
  2. Register a new application in Azure AD
  3. Add Microsoft Graph API permissions for Calendar
  4. Create a client secret
  5. Configure redirect URIs
  6. Use the OAuth 2.0 authorization code flow to get a refresh token

​
Security Considerations

  • Never expose OAuth credentials in client-side code or public repositories
  • Store client secrets and refresh tokens securely (e.g., environment variables, secrets manager)
  • Implement proper error handling for expired or invalid tokens
  • Use HTTPS for all OAuth redirect URIs
  • Regularly rotate OAuth credentials per your security policy
  • Monitor calendar connection status and alert on disconnections

​
Pagination

When listing calendars, use the cursor parameter for pagination: 
let cursor: string | undefined;
const allCalendars = [];

do {
  const params: ListCalendarParams = { cursor };
  const response = await recall.calendar.list(params);
  
  allCalendars.push(...response.results);
  cursor = response.next_cursor;
} while (cursor);

console.log(`Retrieved ${allCalendars.length} total calendars`);

Build docs developers (and LLMs) love

Get started for freeTalk to us