Calendar integrations allow Cal.com to check your availability across multiple calendars and automatically create events when bookings are made.
Overview Cal.com supports integration with major calendar providers:
Google Calendar Microsoft Outlook / Office 365 Apple Calendar (CalDAV) CalDAV-compatible calendars
Calendar integrations serve two primary purposes:
Availability checking : Cal.com reads your calendars to find free time slotsEvent creation : Bookings are written to your destination calendar
You can connect multiple calendars for availability checking but only one destination calendar for new bookings.
Connecting Calendars
Navigate to Calendar Settings
Go to Settings → Calendars from your dashboard
Connect Calendar Provider
Click “Connect” next to your calendar provider (Google, Outlook, etc.)
Authorize Access
Follow the OAuth flow to grant Cal.com permission to access your calendar
Select Calendars
Choose which calendars to check for conflicts (you can select multiple)
Set Destination Calendar
Choose which calendar will receive new booking events
Calendar Types Selected Calendars (Check for Conflicts) // From schema.prisma:1002 model SelectedCalendar { id String @ id @ default ( uuid ()) userId Int integration String // "google_calendar", "office365_calendar" externalId String // External calendar ID credentialId Int ? }
Selected calendars are checked when determining your availability. If you have an event in any selected calendar, that time slot will be marked as busy.
Make sure to select all calendars where you have commitments. If a calendar isn’t selected, Cal.com won’t see those events and may create booking conflicts.
Destination Calendar // From schema.prisma:354 model DestinationCalendar { id Int @ id integration String // Calendar provider externalId String // Which calendar to write to primaryEmail String ? // Email associated with calendar userId Int ? // User-level destination eventTypeId Int ? // Event type-level destination }
The destination calendar is where new booking events are created. You can set:
User-level destination : Default calendar for all your bookingsEvent type-level destination : Specific calendar for certain event types
User-Level
Event Type-Level
All bookings go to the same calendar unless overridden by event type settings. user : { destinationCalendar : { integration : "google_calendar" , externalId : "primary" } }
Specific event types can use different destination calendars. eventType : { useEventLevelSelectedCalendars : true , destinationCalendar : { integration : "office365_calendar" , externalId : "[email protected] " } }
Calendar Sync Cal.com maintains a sync with your connected calendars:
// From schema.prisma:1036-1042 { syncToken : "abc123..." , // Incremental sync token syncedAt : "2024-03-04T10:00:00Z" , syncErrorCount : 0 , syncSubscribedAt : "2024-03-01T00:00:00Z" }
Calendar Watch (Push Notifications) For Google Calendar, Cal.com can subscribe to push notifications:
// From schema.prisma:1029-1033 { channelId : "channel_abc123" , // Watch channel ID channelResourceId : "resource_xyz" , // Resource being watched channelExpiration : "2024-03-11T00:00:00Z" }
Push notifications allow near-instant availability updates when your calendar changes, providing a better booking experience.
Calendar Cache To improve performance, Cal.com caches calendar events:
// Calendar events are cached locally model CalendarCache { credentialId Int key String // Cache key (usually date-based) value Json // Cached events expiresAt DateTime } model CalendarCacheEvent { eventId String calendarId String startTime DateTime endTime DateTime status String // "confirmed", "cancelled" summary String ? }
Availability Checking When someone visits your booking page, Cal.com:
Fetch Events
Retrieves events from all selected calendars (or uses cached data)
Calculate Busy Times
Determines which time slots are occupied
Apply Schedule
Overlays your availability schedule
Apply Buffers
Adds before/after event buffers
Show Available Slots
Displays free time slots to the booker
// Availability checking considers: { selectedCalendars : [ /* all connected calendars */ ], schedule : { /* your working hours */ }, bufferTime : 15 , // User-level buffer beforeEventBuffer : 10 , // Event type buffer before afterEventBuffer : 10 // Event type buffer after }
Event Type Calendar Settings Event types can override user calendar settings:
// From schema.prisma:187, 262 { useEventLevelSelectedCalendars : true , // Use different calendars for this event type useEventTypeDestinationCalendarEmail : true , // Use event type's destination email selectedCalendars : [ /* event type specific calendars */ ] }
Event type-level calendar settings override user-level settings. Make sure the correct calendars are selected.
Calendar Permissions Different calendar operations require different permissions:
Read Permission Required to check availability and view events
Write Permission Required to create/update/delete booking events
Troubleshooting Calendar Sync Calendar Not Syncing
Check Connection Status
Go to Settings → Calendars and verify the calendar shows as “Connected”
Review Permissions
Ensure Cal.com has both read and write permissions to your calendar
Reconnect Calendar
Disconnect and reconnect the calendar to refresh credentials
Check Sync Errors
{ syncErrorCount : 3 , syncErrorAt : "2024-03-04T10:30:00Z" , error : "Invalid credentials" }
Booking Conflicts If bookings are being created during busy times:
Verify selected calendars : Ensure all your calendars are selected for conflict checkingCheck calendar permissions : Cal.com needs read access to all selected calendarsReview event status : Only “confirmed” events block time (tentative events don’t)Clear calendar cache : Force a fresh sync from Settings → Calendars
Calendar Settings by Priority Calendar settings are applied in this order (higher priority overrides lower):
Event type-level destination calendar
User-level destination calendar
Event type-level selected calendars (if useEventLevelSelectedCalendars: true)
User-level selected calendars
Best Practices
Select All Calendars Connect every calendar where you have commitments to prevent double-booking
Use Event Type Calendars Send different event types to different calendars for organization
Monitor Sync Status Regularly check that calendars are syncing without errors
Set Appropriate Buffers Use buffer time to account for travel or preparation between meetings
Advanced: Calendar Watch For Google Calendar, push notifications keep availability updated in real-time:
// From schema.prisma:1051-1054 { watchAttempts : 0 , unwatchAttempts : 0 , maxAttempts : 3 , lastErrorAt : null }
Watch channels automatically renew before expiration. If watch fails after maxAttempts, Cal.com falls back to polling.
