GudCalGudCal
Docs
Google Calendar

Google Calendar

Connect Google Calendar for conflict detection and event sync.

GudCal integrates with Google Calendar to automatically check for conflicts when guests book meetings and create calendar events on confirmation.

Features

  • Conflict detection — Busy times from your Google Calendar block availability
  • Event creation — Confirmed bookings appear in your calendar automatically
  • Google Meet links — Auto-generated when event location is set to Google Meet
  • Encrypted tokens — OAuth refresh tokens are stored with AES-256-GCM encryption

Environment Variables

# Google Calendar OAuth (separate from login OAuth)
GOOGLE_CALENDAR_CLIENT_ID="your-calendar-client-id.apps.googleusercontent.com"
GOOGLE_CALENDAR_CLIENT_SECRET="your-calendar-secret"
 
# Encryption key for storing OAuth tokens (32-byte hex)
ENCRYPTION_KEY="your-64-character-hex-string"

Generate the encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Google Cloud Setup

Enable the Google Calendar API

  1. Go to the Google Cloud Console
  2. Select your project (or create one)
  3. Navigate to APIs & Services → Library
  4. Search for Google Calendar API and enable it

Create OAuth credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Application type: Web application
  4. Add authorized redirect URIs:
    • Local: http://localhost:3000/api/calendar/google/callback
    • Production: https://yourdomain.com/api/calendar/google/callback
  5. Copy the Client ID and Client Secret

Add scopes to consent screen

Make sure your OAuth consent screen includes:

  • https://www.googleapis.com/auth/calendar.readonly (read busy times)
  • https://www.googleapis.com/auth/calendar.events (create/delete events)

Connecting Your Calendar

Once configured, users connect their calendar from Dashboard → Integrations → Google Calendar. The OAuth flow grants GudCal read/write access to their calendar.

The Google Calendar credentials for calendar sync are separate from the Google OAuth credentials used for login. You need both if you want Google login AND calendar integration.

How It Works

  1. When a guest views available times, GudCal fetches busy periods from the host's Google Calendar and removes conflicting slots
  2. When a booking is confirmed, GudCal creates a Google Calendar event with the meeting details
  3. If the event type uses Google Meet, a Meet link is auto-generated and included in the booking confirmation email
  4. When a booking is cancelled, the corresponding calendar event is deleted
EmailWebhooks