How to connect Google Workspace to Voxbi

One Google Workspace connection gives Voxbi two independent halves: your team's calendars, and their contacts. Switch on either one, or both. Each half asks Google for its own permissions, and a Google Workspace super administrator authorizes the whole thing once, for everybody. Your team is never prompted and never sees a consent screen.

Setup takes about 20 minutes and touches two products, so read the "who does what" table before you start.

What the integration does

Calendars. While someone has a meeting in their calendar, Voxbi puts them on the meeting status, and takes them off it when the meeting ends. Approved absences are written to their calendar, and removed again if the absence is cancelled. Both features belong to the Tempus time-tracking module and need it active. If you only want the status side, the call flows and presence page explains what it changes for callers.

Contacts. Voxbi contacts appear in each linked employee's Google account, filed under a label you choose, which is also how they reach the phone for caller identification. In the other direction, each employee's own Google contacts are read into Voxbi as private contacts that only they can see. Contacts work with or without Tempus.

Who does what

A delegated or partial Google administrator cannot grant this. It has to be a super administrator.

Before you start

• You can sign in to the Voxbi Cockpit as an administrator.

• A Google Workspace super administrator is available.

• You know every domain your employees' email addresses use, including secondary ones.

• For the calendar features, the Tempus module is active.

• You have a real Workspace mailbox to test with.

Step 1: create the integration

In the Voxbi Cockpit, go to Configuration, then Integrations, and choose Add integration. Set Type to Google Workspace. The form changes to the Google setup as soon as you do.

Two fields define the boundary of the connection.

The domain list matters more than it looks. Every customer authorizes the same Voxbi client identifier, and Google's delegation has no concept of one phone system versus another. This list is what keeps one customer's grant from reaching another's mailboxes. Removing a domain later switches off the links of everyone in it, in the same save.

Step 2: choose which halves you want

Do this before you copy anything. The permission list Voxbi gives you in step 3 covers exactly the halves that are switched on, so deciding now means the super administrator pastes one list, once. Switch a half on six months later and the list grows, which sends them back to the Admin console.

On the Calendar tab, "Use calendars" is the master switch for the meeting status and absence events. It is on by default.

On the Contacts tab, "Use contacts" is off by default, because contact sync reads employees' personal address books and nobody should be opted into that by accident. If you switch it on, choose at least one direction. Switching contacts on without a direction is refused on save: it would ask your administrator for contact permissions and then sync nothing.

Step 3: copy the two values

Back on the General tab, the first step of the form shows the two values the Google Workspace super administrator needs. Both have a copy button and both are read only.

The Calendar and Contacts tabs each show a shorter list of their own. Those are reference only. Pasting one of them instead of the combined list is the most common way to end up with a half-authorized integration.

What the permissions allow:

• Calendars. List the calendars an employee has, read the start and end of the events on them, and create, update or delete events. Voxbi only ever edits or deletes an event it created itself, and it never stores the title of a meeting marked private, personal or confidential.

• Contacts. Read an employee's own Google contacts, and create, update or delete contacts in their account. Voxbi only touches the ones it created, which is what the label in step 8 is for.

• Shared contacts, only if you enable that import. Read the contacts an administrator has shared with the whole Workspace. Read only: Voxbi never writes to the shared address book.

Step 4: authorize Voxbi in the Google Admin console

This is the only part that happens outside Voxbi, and a Google Workspace super administrator does it. Google calls this domain-wide delegation: one administrator authorizes Voxbi once, for the whole Workspace, with no consent redirect and no per-employee sign-in.

Sign in to admin.google.com as a super administrator, then open Security, Access and data control, API controls, Domain-wide delegation. The "Open Google Admin console" button on the Voxbi form goes straight there.

1. Choose Add new.

2. Paste the client identifier from step 3.

3. Paste the permission list from step 3 into the OAuth scopes field. It is already comma separated, which is the format the field expects.

4. Choose Authorize.

Google's grant is all or nothing. If one permission is missing, the whole authorization fails, and the error does not say which one. Google also needs a few minutes: if the check in step 5 fails right after you authorize, wait and run it again before changing anything.

Step 5: check that it worked

Back on the General tab, choose Verify authorization. Voxbi signs in as the verification account from step 1 and reads one calendar. It writes nothing to anybody's calendar.

A successful check reports each half separately and turns the banner at the top of the form green. Until it succeeds, the Active switch stays unavailable.

Step 6: switch it on

Turn Active on and save. Nothing syncs until this is on. At this point Voxbi is authorized for the whole Workspace, and it is still syncing nobody, because no employee is linked yet.

Step 7: set up the calendar half

On the Calendar tab, one choice matters more than the rest: where Voxbi writes absence events.

A separate calendar the employee can hide (recommended). Voxbi creates a calendar inside the employee's own Google account and writes only there. They can hide it with one click, and nothing Voxbi writes touches their personal calendar. The trade-off: these appear as ordinary busy entries. Google reserves real out-of-office behaviour 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 main calendar (more visible). Real out-of-office behaviour: the badge, automatic declining of invitations, and visibility to colleagues checking whether someone is free. The trade-off: the employee cannot hide these, because they sit among their own events.

The calendar name applies to calendars created from then on. Changing it does not rename calendars that already exist, and an employee is free to rename their own copy.

Only the employee's primary calendar is read. A meeting on a secondary calendar they own, or on a shared team calendar, does not change their status.

If the meeting status card says it is not configured, the missing piece lives in Tempus settings: which status counts as being in a meeting, and which statuses may be converted into it. The card links to the right screen. Absence events need nothing beyond a linked employee.

Step 8: set up the contacts half

Skip this step if you are not using contacts. On the Contacts tab, choose one or both directions.

Voxbi to Google. Voxbi contacts appear in each linked employee's Google account, and they only ever receive contacts they can already see in Voxbi. You can also push their own private contacts back into their Google account, one copy each. Contacts Voxbi creates are filed under a label you choose, so employees can tell them apart from their own and hide them if they want. Renaming the label renames it in each account and leaves the contacts in it untouched.

Google to Voxbi. Each linked employee's own Google contacts are read into Voxbi as private contacts, visible only to them. You can also import the contacts an administrator shares with the whole Workspace, which then become visible to everyone in Voxbi. That is the one option that needs the extra read-only directory permission.

Step 9: link employees to their Google accounts

This is the step that starts the sync. Authorizing covers the whole Workspace; Voxbi syncs an employee only once their Voxbi user is linked to their Google address.

Go to Tempus, Attendance, Calendar links. You can also get there from the Manage calendar links button on the Calendar tab.

Choose Match calendar accounts to link everybody at once. Voxbi 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. You see what it will do before it does it.

Anyone whose Voxbi email differs from their Workspace address is listed as not linked and can be linked by hand. The address is checked against Google before it is saved. Each employee can be switched off entirely, or opted out of just one feature.

Linked employees start syncing on the next run.

What Voxbi reads, and what it does not

Worth reading before you present this to your team, because it answers the questions they ask.

How often things run

If the authorization check fails

The check reports each stage separately and names what it tried, so a failure points at one cause rather than at the whole setup.

Frequently asked questions

Do employees have to approve anything?

No. Google's domain-wide delegation is granted once by a super administrator for the whole Workspace. Employees see no consent screen, get no prompt, and sign in exactly as before.

The integration was working and stopped. Why?

A super administrator can revoke domain-wide delegation at any time, and Google does not notify Voxbi. Voxbi re-checks every authorization weekly and deactivates an integration whose grant has gone, rather than letting it look healthy while syncing nothing. Re-authorize in the Admin console and run the check again.

Everything is authorized but nobody is syncing.

Check step 9. Authorizing covers the Workspace; linking covers the person. The Calendar tab shows how many employees are linked.

Why did a feature start asking for re-authorization?

Switching on a half that was not part of the original grant adds permissions to the list. Copy the list from the General tab again and have the super administrator paste the new one.

Can I use this without the Tempus module?

Contacts work on their own. The meeting status and absence events are Tempus features and need it active.