---
title: 'Google Workspace integration'
slug: google-workspace-calendar-integration
summary: "Connects a Google Workspace so Cockpit can read employees' calendars to set a meeting status, and write approved absences onto a calendar of their own."
module: telephony
section: features
order: 90
tags:
  - telephony
  - integrations
  - google
  - tempus
updated: '2026-09-09'
---

> The Google Workspace integration connects a customer's Google Workspace to your PBX. One Workspace super administrator authorizes Cockpit once, for the whole company, and employees are never prompted.

## Overview

Configured as an [integration](integrations.md) of type Google Workspace, it powers two [Tempus](../tempus/) features, both optional and both switchable per employee:

| | |
|---|---|
| **Meeting status** | While a meeting runs, the employee's Tempus status changes to the meeting status you chose, and reverts when it ends. |
| **Absence events** | An approved absence appears on the employee's calendar, and is removed if the absence is canceled. |

Both require Tempus to be active for the PBX. The employee-facing side of all this — what colleagues see, which calendar the events land on, what is deliberately never read — is documented in [Google Workspace calendar](../tempus/google_calendar_integration.md). This page covers the integration form itself.

## How the authorization works

There is no consent redirect. Google calls this **domain-wide delegation**: the customer's super administrator authorizes Cockpit's service account once, in the Google Admin console, for the whole company.

Create the integration and save it first: the authorization check only appears once the integration exists, because it needs something to record its result against. The General tab then walks through four steps. A status card at the top always shows where things stand: one badge for the whole integration (Connected, Ready to enable, or what is still missing), the organization's domains, when the admin authorization was last verified, and one state per service (Calendar and Contacts each read Enabled, Off, or Not authorized). The test user and the verified date sit under "How Google Workspace access works".

1. **Authorize in Google Admin.** The Client ID and a humanized permissions block sit above the button: an API chip per feature switched on, and "View all N permissions" expands to each scope's plain-language label next to its raw URL. The button opens the domain-wide delegation dialog with the client ID and the permissions already in it, so the administrator only has to sign in as a super administrator of that Workspace and choose Authorize. Google can take a few minutes to apply a new grant.
   Doing this from another account, or the dialog opened empty? The Client ID and the permissions sit under the button too, to add by hand under Security → Access and data control → API controls → Domain-wide delegation → Add new. The scope list in particular must be complete: a partial list fails the whole authorization without saying which scope is missing.
2. **Choose Workspace domains.** One row per domain Cockpit may act for, added or removed as needed. Cockpit never touches an address outside these domains.
3. **Test the connection.** Enter a test user, any real Workspace account in one of the domains above, then press **Verify connection**. The result replaces the button in place: a row per check (authorization, calendar access, and contacts access when that half is switched on) and a sentence naming the exact gap on a failure, for example "Calendar access succeeded, but the contacts permissions are missing from the domain-wide delegation." **Test again** re-runs the check without leaving the page.
4. **Enable integration.** Nothing syncs until this switch is on, and it stays disabled until step 3 succeeds. A one-line summary beside the switch says whether Calendar and Contacts are each on or off.

Switching a feature on later can add a permission. The form says so, and the button then carries the complete list again: authorizing it a second time replaces what the client ID had, it does not add a duplicate.

Each feature tab opens with a header showing whether that half is switched on (**Enabled**/**Off**) and whether Google has authorized it (**Connected**, or **Action required**), the same answers the status card gives. At the bottom of the tab, a **Google permissions** disclosure holds the permissions block: a primary **Authorize in Google Admin console** button while this half needs it, or a quiet **Reauthorize** link once it is healthy. Both submit the same combined scope list every enabled service needs, the one the General tab's own console step uses, because the console replaces a client ID's whole grant rather than merging into it — there is no button anywhere on this form that authorizes one half alone.

The check mints a delegated token and reads one calendar. It writes nothing to anybody's calendar.

## Where absence events are created

A per-company choice on the form, and the more consequential of the two settings:

- **A separate calendar the employee can hide** *(recommended)* - Cockpit creates a calendar in the employee's own Google account and writes there. They can hide it with one click, and nothing Cockpit writes touches their personal calendar.
  - Trade-off: these appear as ordinary busy entries. Google reserves genuine out-of-office behavior for the main calendar, so there is no out-of-office badge, invitations are not declined automatically, and colleagues checking availability will not see the absence.

- **Directly on the employee's main calendar** - Real out-of-office behavior: the badge, automatic declining, and visibility to colleagues.
  - Trade-off: the employee cannot hide these, since they sit among their own events.

An absence event is titled after the kind of absence and the days it covers, for example *Sick Leave (Sep 8, 2026)*, and the absence's note in Cockpit becomes the event body. The title names the category, so anyone the employee has granted "see all event details" on that calendar can read that a day off was sick leave. Worth weighing before choosing the main calendar.

A published Tempus schedule writes each shift to the same calendar, titled *Shift* with the schedule's name. It follows the choice above, but belongs to neither service on this form and has no per-employee switch: any linked employee can receive one.

## Which calendars are read

The employee's **primary** calendar always, and nothing else by default. A meeting living on a secondary calendar they own, or on a shared team calendar, does not change their status unless that calendar is added to their record: the **Google Workspace** tab on a user carries an **Extra calendars** picker, up to five, and each one is read on every sweep alongside the primary calendar. It appears once the employee is linked, because it lists what their own account holds, and the calendar links list then shows **Also reads** for them. Picking extras costs one more read per employee per sweep, which is what the cap is for.

Cockpit does not mistake its own writes for meetings. Events it created are recorded at the moment of creation and excluded from the status logic, which matters most with "events on the main calendar": Google has no out-of-office event type outside the primary calendar, so an absence written there is an ordinary busy event, and a half day is not an all-day one.

## Google Workspace domains

The allowed-domain list is the boundary of the whole integration: Cockpit only ever acts for an address in one of these domains, whatever else the Workspace authorization would permit.

Include every domain your employees' addresses use, including secondary ones. A person at `name@subsidiary.com` is not touched unless `subsidiary.com` is listed. Removing a domain switches off the mappings of everyone in it, in the same save.

## Linking employees

Cockpit matches employees to their Google address by email and proves each match by reading that account's own calendar, so a link is verified rather than assumed. Anyone whose Cockpit email differs from their Workspace address is listed as unlinked and can be linked by hand, with the address checked against Google before it is saved. Each employee can be switched off entirely, or opted out of a single feature: the meeting status, absence events, and contact sync each have their own switch on the row.

## If verification fails

- **"Google refused the authorization."** - The grant was authorized in a different Workspace, the client ID or the scope list was not pasted exactly, or Google has not applied the change yet. Re-open the button's link as a super administrator of that Workspace and try again in a few minutes.

- **"Google does not recognize that address."** - The verification mailbox does not exist in this Workspace, or it lacks a Calendar license. Try a different real address.

- **"That address is not in one of the allowed domains."** - Add the domain to the list first. This is also the common case for an employee on a secondary domain.

- **"Cockpit's connection to Google is not configured on this server."** - Nothing on this page can fix it and the fields stay read-only until it is. Contact support.

- **"Google rejected our service account."** and **"The Google Calendar API is not enabled on our side."** - Also Voxbi's side of the connection rather than the customer's Workspace. Contact support.

- **"Google returned an unexpected error."** - Nothing the check could classify. Try again; if it repeats, send the message shown under the failed stage to support.

## See also

- [Google Workspace calendar](../tempus/google_calendar_integration.md) - the employee-facing side: what is read, what is written, and what is never stored.
- [Integrations](integrations.md) - the shared form and the other types.
- [Tempus employees](../tempus/tempus_employees.md) - who the calendars belong to.
- [Events](events.md) - where sync outcomes are logged.