My Blog

Google Calendar Integration

Google Calendar Integration — Setup Guide

Google Calendar Integration — Setup Guide

This guide explains how to enable company-level Google Calendar integration to automatically sync job appointments. Follow each step carefully.

Part 1: Google Cloud Console Setup (Required First)

Step 1: Create Google Cloud Project

  1. Open your browser and go to: https://console.cloud.google.com/
  2. Sign in with your Google account.
  3. Create a new project or select an existing one:
    • Click the “Select a project” dropdown at the top of the page.
    • Click “New Project”.
    • Enter a project name (e.g., YourCompany Calendar Integration).
    • Click “Create”.

Step 2: Enable Google Calendar API

  1. Go to: Google API Library.
  2. Type Google Calendar API in the search bar.
  3. Click on the result for Google Calendar API.
  4. Click the Enable button.

Step 3: Create OAuth 2.0 Credentials

  1. Go to: Credentials.
  2. Click Create Credentials → OAuth client ID.
  3. If prompted, configure the OAuth consent screen:
    • Click “Configure consent screen”.
    • Select “External” (unless your company uses Google Workspace).
    • Fill in the required details:
      • App name: Enter your company name.
      • User support email: Enter your email address.
      • Developer contact information: Enter your email address again.
    • Click “Save and Continue”.
    • Skip scopes for now by clicking “Save and Continue” again.
    • Add test users if needed, then click “Save and Continue”.
  4. Create OAuth Client ID:
    • Application type: Web application.
    • Name: Calendar Integration Client.
    • Add the following Authorized redirect URIs (replace yourdomain.com with movematebend.co.uk): 
      https://yourdomain.com/api/oauth/google/callback
yourapp://oauth/callback
      to look like this 
      https://movematebend.co.uk/api/oauth/google/callback
yourapp://oauth/callback
  5. Click Create.
  6. Download the JSON credentials file:
    • Click “Download JSON” and save it somewhere safe on your computer.
    • Open the file (usually named something like client_secret_xxxxx.apps.googleusercontent.com.json) using Notepad.
    • Look for these values in the JSON: 
      {
  "web": {
    "client_id": "your-client-id.apps.googleusercontent.com",
    "client_secret": "GOCSPX-your-client-secret",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    ...
  }
}
    • Copy these two values perhaps into a new notepad file which can be saved if you prefer optional:
      • Client ID: The string ending with .apps.googleusercontent.com
      • Client Secret: The string starting with GOCSPX-
    • You will use these later in the app Company Admin Dashboard.

Step 4: Configure OAuth Consent Screen Scopes

  1. Return to: OAuth Consent Screen.
  2. Click Edit App.
  3. Go to the Scopes tab.
  4. Click Add or Remove Scopes.
  5. Add the following scopes: 
    https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events
  6. Click Update and then Save and Continue.

Part 2: Company Admin Setup (In Your App)

Step 1: Access Calendar Integration

  1. Log in to your app as a company owner/admin (role level 6+).
  2. Go to the Company Admin Dashboard.
  3. Click on Calendar Integration (or go directly to /calendar).

Step 2: Configure OAuth Credentials

  1. In the OAuth Config section, enter the following:
    • Client Type: Web application (this will be pre-filled).
    • Client ID: Paste the Client ID you copied earlier from the JSON file.
    • Client Secret: Paste the Client Secret you copied earlier from the JSON file.
    • Authorized Redirect URIs: Enter the same values you configured in Google Cloud: 
      https://yourdomain.com/api/oauth/google/callback
yourapp://oauth/callback
    • Scopes: 
      https://www.googleapis.com/auth/calendar
  2. Click Save OAuth Config.

Step 3: Connect Google Calendar

  1. Click the Connect Google Calendar button.
  2. You will be redirected to Google’s authorization page.
  3. Log in with the Google account that has the calendar you want to sync.
  4. Click Allow to grant permissions.
  5. You will be redirected back to your app with a success message.

Step 4: Configure Calendar Settings

  1. Expand the Calendar Settings section.
  2. Set the options:
    • Enable Auto-sync Jobs to automatically create events for new jobs.
    • Enable Sync Pickups to create events for pickup appointments.
    • Enable Sync Deliveries to create events for delivery appointments.
    • Enable Include Customer in Events to add the customer’s email as an attendee.
    • Event Duration: Enter the default duration in minutes (e.g., 60).
    • Event Title Template: Customize the event title format (e.g., Job #{jobId} - {eventType} - {customerName}).
  3. Your settings will be saved automatically.

Part 3: User Access and Permissions

Admin Users (Platform Level)

  • Have full access to calendar integration management across all companies.
  • Can view and manage all company integrations.
  • Location: Admin dashboard → Calendar Management.

Company Users

  • Owner/Manager (Role Level 6+):
    • Can configure OAuth credentials.
    • Can connect/disconnect calendar.
    • Can modify settings.
    • Can create manual events.
  • Staff (Role Level < 6):
    • Can only view integration status.
    • Cannot change settings or credentials.
    • Jobs they create will still sync automatically if enabled.

Part 4: Testing the Integration

  1. Create a test job with pickup/delivery dates.
  2. Check your Google Calendar at calendar.google.com.
  3. Verify the job appears with correct details.
  4. Modify the job details and confirm updates appear in the calendar.

Troubleshooting Common Issues

  • “OAuth Error” or “Invalid Client”: Check that the Client ID and Secret are entered correctly, and confirm that Redirect URIs match exactly.
  • “Insufficient Permissions”: Confirm you are logged in as a role level 6+ user, and ensure consent screen scopes were configured properly.
  • “Events Not Syncing”: Check that auto-sync settings are enabled and integration shows as Connected. Try creating an event manually to test.

Part 5: Security Best Practices

For Company Admins

  1. Use a dedicated Google account for integration.
  2. Regularly review connected applications in your Google Account settings.
  3. Monitor calendar events for accuracy.
  4. Keep OAuth credentials secure — never share your Client Secret.

For Platform Admins

  1. Monitor OAuth usage across companies.
  2. Apply rate limits to API calls.
  3. Log integration activities for auditing.
  4. Ensure company data remains isolated.

Part 6: API Management (If Enabled)

Company API Access

  • Location: Company Admin → API Management
  • Features include:
    • Generate API keys for third-party integrations.
    • Monitor API usage and rate limits.
    • Configure webhook endpoints for calendar events.
    • Manage external application access.

Integration Endpoints

POST /api/trpc/calendar.integrations.createEvent
POST /api/trpc/calendar.integrations.syncJob
GET  /api/trpc/calendar.integrations.getEvents

Part 7: Support and Maintenance

Regular Maintenance

  1. Monitor token expiration (Google tokens expire regularly).
  2. Check API quotas in Google Cloud Console.
  3. Review sync accuracy at least monthly.
  4. Update OAuth consent screen if app details change.

Getting Help