Skip to main content

Google Calendar Integration

The Google Calendar integration connects Harmony to your organization's Google Calendars so that scheduled meetings can be surfaced in Harmony, the Companion Bot can auto-join supported meeting links, and event metadata (titles, attendees, times) can flow into transcripts, insights, and action items. Like the rest of Google's APIs, Calendar uses OAuth 2.0 for authorization — which means you (the workspace admin) register a Google Cloud OAuth application, enable the Google Calendar API on it, and paste the resulting Client ID and Client Secret back into the Harmony setup form.

Once configured at the workspace level, anyone in your organization who connects their Google Calendar will be routed through your own Google Cloud OAuth app — you don't have to share credentials, and each user still controls which of their calendars are synced.

Configuring the Google Calendar integration at the workspace level requires the integrations:write:all permission. See Roles and permissions. Once the workspace credentials are saved, individual users can connect their own Google Calendar from Marketplace → Apps → Google Calendar — see Personal integrations for the user-side flow.

Step 1. Open the Marketplace​

In Harmony, open the Marketplace tab from the sidebar and select the Google Calendar integration tile.

Step 2. Click "Set up"​

After clicking Set up, Harmony shows a setup form. This form contains everything you need to wire your Google Cloud OAuth application to Harmony, including:

  1. The Redirect URI to register in Google Cloud.
  2. The list of required OAuth scopes.
  3. A field for the Client ID.
  4. A field for the Client Secret.

You will copy values from this form into your Google Cloud setup, then copy the generated Client ID and Client Secret back into this same form. Google uses OAuth 2.0 for this authorization flow.

Step 3. Open Google Cloud Console and prepare a project​

Sign in to the Google Cloud Console and create a new project (or select an existing one) to host this integration. Google recommends using a dedicated project for OAuth-based access to Google APIs so that scopes, credentials, and audit history stay isolated from other workloads.

If you have already created a Google Cloud project for the Google Meet or Google Email integration, you can reuse it here — just enable the Google Calendar API on the same project in the next step. Each integration still needs its own OAuth client (Client ID + Client Secret), since each one uses a different redirect URI.

Step 4. Enable the required API​

Inside the project, enable the API that the Google Calendar integration needs. Google OAuth integrations require the relevant API access to be enabled before authorization can complete successfully.

Enable the following API:

  • Google Calendar API

Step 5. Set up the Google Auth Platform​

Once the API is enabled, configure the Google Auth Platform / OAuth consent screen. This is the screen users see when Google asks them to authorize the application.

5.1 App information​

Fill in the basic app details:

  • App name — what users see on Google's consent screen (for example, "Harmony — Google Calendar").
  • User support email — a contact address users can reach if something goes wrong with authorization.

5.2 Audience​

Select External as the audience type so anyone in your organization (and any guest users you invite) can authorize the app.

5.3 Contact information​

Provide the required developer contact email addresses. Google sends notifications about your OAuth app — such as verification updates or policy issues — to these addresses.

5.4 Finish​

Review all the information and click Create to complete the Google Auth Platform setup.

Step 6. Add the required scopes​

Copy the scopes shown in the Harmony setup form and paste them into the Google Auth Platform configuration, then save the selected scopes.

The setup form lists the minimum scopes the Calendar integration needs. Adding fewer scopes will cause features such as listing calendars, reading events, or creating/updating events to fail. Adding extra scopes is unnecessary and may delay Google's app verification.

Step 7. Create the Client ID and Client Secret​

Step 7.1 Choose application type​

Set the application type to Web application and give it a recognizable name — for example, "Harmony — Google Calendar".

Step 7.2 Set Authorized JavaScript origins​

Set Authorized JavaScript origins to:

https://app.heyharmony.com

Step 7.3 Set Authorized redirect URIs​

Set Authorized redirect URIs to the value shown in the Harmony setup form. For Google Calendar this is:

https://app.heyharmony.com/integrations/oauth/google-calendar/callback

Google compares the redirect URI character-for-character at sign-in time. A trailing slash, an extra path segment, or http:// instead of https:// will cause the authorization to fail with an "Access blocked: invalid request" error.

Step 7.4 Copy the Client ID and Client Secret​

After clicking Create, Google shows a panel with your Client ID and Client Secret. Copy both values — you will paste them back into Harmony in the next step.

Treat the Client Secret like a password. Anyone with both the Client ID and Client Secret can impersonate the integration. If a secret leaks, rotate it in Google Cloud and update it in Harmony.

Step 8. Paste the credentials into Harmony​

Return to the Harmony setup form and paste the Client ID and Client Secret into the matching fields, then save.

Once saved, Harmony shows a summary of the configured application on the right side of the integration page so you can confirm the values at a glance.

From now on, anyone in your organization who connects Google Calendar from Marketplace → Apps → Google Calendar will be routed through your OAuth application. Each user signs in with their own Google account and chooses which of their calendars to sync — Harmony does not share calendars between users.

What the Google Calendar integration unlocks​

Once a user connects Google Calendar, Harmony and Companion can:

  • Show upcoming meetings in the Meetings start view, so users always see what's next without leaving Harmony.
  • Auto-join scheduled meetings with the Companion Bot — when auto-join is fully enabled, synced events with supported Google Meet / Zoom / Microsoft Teams links are evaluated for automatic bot scheduling. Auto-join is gated by several layers (deployment feature flag, backend kill-switch, workspace toggle, the user's personal preference, a connected and synced calendar, a supported meeting URL, and a scheduling window) — see Recording modes — Auto-Join and Auto-join meetings for the full layered model.
  • Surface event context in transcripts and insights — attendees, event titles, and times are linked back to the underlying calendar event.
  • Create, update, and read events from Companion threads or as part of action item follow-up, with the user's confirmation before any change is written back to the calendar.

Calendar data is scoped to the individual user who connected it. Connecting Google Calendar at the workspace level only stores the OAuth application credentials — it does not give admins access to anyone's personal calendar.

Troubleshooting​

  • "Access blocked: This app's request is invalid" — the Authorized redirect URI in Google Cloud does not exactly match the one shown in the Harmony setup form. Re-check the URI character-for-character, including the /integrations/oauth/google-calendar/callback path.
  • "Error 403: access_denied" after authorization — one or more required scopes were not added on the OAuth consent screen, or the Google Calendar API was not enabled in Step 4. Re-check the scope list and that the API is enabled in the same project as the OAuth client.
  • Authorization succeeds but calendars don't appear — confirm that the Google Calendar API is enabled on the same Google Cloud project the OAuth credentials belong to, not a sibling project. Also confirm the user has at least one calendar visible on their Google account.
  • Auto-join isn't picking up events — auto-join is gated by multiple layers, so enabling the workspace toggle alone is not enough. Walk through all of them in order: the bot-auto-join Reflag feature flag is on for your deployment, the backend env kill-switch HARMONY_REMOTE_AUTOJOIN is set to "true", Workspace Settings → Experimental has auto-join enabled, the user's Preferences → Experimental auto-join setting is on and not in manual mode, the user's calendar is connected and syncing, the event has a supported Google Meet / Zoom / Microsoft Teams link, the event title doesn't match an exclude pattern, and the event start is inside the scheduling window (more than ~2 minutes out and within the next 28 days). Events that exist only on a Microsoft 365 / Outlook calendar are not picked up at all; see Workspace integrations → Microsoft Teams. The full layered model is documented in Recording modes — Auto-Join and Auto-join meetings.
  • You need to rotate the secret — generate a new client secret in Google Cloud, then update it in the Harmony setup form. The Client ID can stay the same; existing user connections do not need to be rebuilt.
  • "This app isn't verified" warning shown to users — while your OAuth app is still in Testing or pending Google verification, users see an "unverified app" screen. They can still continue if they trust the workspace. For production rollout, submit the app for verification from the Google Auth Platform page.