Overview
The Google Calendar integration provides:- Automatic event creation upon payment approval
- Google Meet link generation for virtual classes
- Calendar synchronization with admin’s Google Calendar
- Event management and updates
- Time zone handling (America/Argentina/Buenos_Aires)
Prerequisites
Before configuring Google Calendar integration:- Google Cloud Platform account
- Google Calendar API enabled
- OAuth 2.0 credentials configured
- Admin user email set in environment variables
Environment Configuration
Required Environment Variables
The Google Calendar ID where events will be created. Typically the admin user’s email address:
Google Calendar API key for reading calendar availability. Obtain from:
- Google Cloud Console > APIs & Services > Credentials
- Create API Key
- Restrict to Calendar API only
OAuth 2.0 Client ID from Google Cloud Console
OAuth 2.0 Client Secret from Google Cloud Console
OAuth callback URL:
Email of the admin user whose calendar will be used
src/app/api/calendar/route.ts:10, 47-55
Optional: Service Account
Service account credentials for server-to-server authentication.
Use this instead of OAuth if you don’t need user-specific permissions.
The current implementation uses OAuth 2.0 with refresh tokens rather than service accounts. Service account code is commented out in the codebase.
Google Cloud Console Setup
Step 1: Create/Select Project
- Go to Google Cloud Console
- Create a new project or select existing:
- Project name: “Speak English Now” (or your choice)
- Organization: Your organization (optional)
Step 2: Enable Google Calendar API
- Navigate to “APIs & Services” > “Library”
- Search for “Google Calendar API”
- Click “Enable”
Step 3: Create OAuth 2.0 Credentials
- Go to “APIs & Services” > “Credentials”
- Click ”+ CREATE CREDENTIALS” > “OAuth client ID”
-
Configure consent screen if prompted:
- User Type: External (for testing) or Internal (for organization)
- App name: “Speak English Now”
- User support email: Your admin email
- Developer contact: Your admin email
-
Add OAuth scopes:
-
Create OAuth Client ID:
- Application type: Web application
- Name: “Speak English Now Web Client”
- Authorized JavaScript origins:
- Authorized redirect URIs:
-
Copy credentials:
- Client ID →
AUTH_GOOGLE_ID - Client Secret →
AUTH_GOOGLE_SECRET
- Client ID →
Step 4: Create API Key
- Go to “APIs & Services” > “Credentials”
- Click ”+ CREATE CREDENTIALS” > “API key”
- Restrict the API key:
- Click on the created key to edit
- API restrictions: “Restrict key”
- Select “Google Calendar API”
- Save
- Copy API key →
CALENDAR_API_KEY
OAuth Scopes Configuration
The application requests specific calendar permissions: Implementation:src/auth.ts:19-25
Scope Breakdown
OpenID Connect authentication
Access to user’s email address
Access to user’s basic profile information
Create, read, update, and delete calendar events
Request refresh token for persistent access
Refresh Token Storage
For persistent calendar access, the admin user’s refresh token is stored in the database.Capturing Refresh Token
Implementation:src/auth.ts:73-76
- Only captured for the admin user
- Stored in the User model’s
googleRefreshTokenfield - Used to create access tokens for calendar API calls
Database Storage
Function:src/services/functions/index.ts:9-22
Retrieving Refresh Token
Function:src/services/functions/index.ts:24-37
Reading Calendar Events
The system can fetch existing calendar events to check availability.GET Calendar Events
API Route:src/app/api/calendar/route.ts:9-36
- Uses API key authentication (read-only)
- Fetches events from current time forward
- Returns simplified event data (start, end, status)
- Used for checking availability when booking
Creating Calendar Events
When a payment is approved, the system creates a Google Calendar event with a Meet link.Event Creation Flow
API Route:src/app/api/calendar/route.ts:40-86
Event Structure
Function:src/services/functions/index.ts:115-154
Event Configuration
Event title displayed in calendar: “Clase de Inglés”
Event description with class type and participant count
Class start time in ISO format
Time zone:
America/Argentina/Buenos_AiresConfiguration for Google Meet link generation
Unique identifier for the Meet link (must be unique)
Must be
hangoutsMeet for Google Meet linksMust be
1 to enable conference data (Google Meet link)opaque - Shows as busy; transparent - Shows as freeGoogle Meet Link Extraction
After event creation, the Google Meet link is extracted and stored: Implementation:src/services/functions/index.ts:191-205
Time Zone Handling
All calendar events use Argentina time zone:- Frontend sends dates in user’s local time
- Backend converts to Argentina time for storage
- Calendar events specify time zone explicitly
Listing Events (Admin)
Admins can list all upcoming events: Function:src/services/functions/index.ts:77-109
This function uses service account authentication (currently commented out). For production use, adapt it to use OAuth2 with refresh token.
Troubleshooting
”Refresh token not found”
Solution:- Admin user must sign out completely
- Clear browser cookies
- Sign in again to trigger refresh token capture
- Check database that
googleRefreshTokenis stored
”Invalid grant” error
Causes:- Refresh token has been revoked
- User changed password
- Too many refresh tokens issued
- Revoke access in Google Account Settings
- Sign in again as admin
- Grant permissions again
”Calendar API not enabled”
Solution:- Go to Google Cloud Console
- APIs & Services > Library
- Search “Google Calendar API”
- Click “Enable"
"Meet link not generated”
Check:conferenceDataVersion: 1is setconferenceSolutionKey.type: 'hangoutsMeet'is correct- Google Meet is enabled for your Google Workspace
- Calendar has permissions to create Meet links
”Events showing in wrong time zone”
Solution:- Verify
timeZoneis set in event object - Check frontend sends ISO 8601 formatted dates
- Ensure server time zone is configured correctly
Security Best Practices
API Rate Limits
Google Calendar API has usage limits:- Queries per day: 1,000,000 (default)
- Queries per user per second: 5
Related Resources
Google Calendar API Documentation
Official Google Calendar API documentation
OAuth 2.0 Documentation
Google OAuth 2.0 implementation guide
Payment Integration
Payment flow that triggers calendar event creation
Class Management
Managing virtual classes and events