Google Workspace Connector

Connect Gmail, Google Calendar and Google Drive with your own Google account

The Google Workspace connector gives the agent access to your Gmail, your calendars, and your Google Drive including shared drives. By default it is read-only. An admin can also allow it to create and update calendar events and edit Sheets and Docs, and each person then chooses whether to allow that for their own account. Every change is shown to you for approval before it is made. Email is never sent and files are never deleted.

This is the per-user OAuth connector: you sign in with your own Google account and the agent sees exactly what you can see. If you instead want a shared bot identity that reads and writes specific Sheets, see the Google Drive service account connector.

Setup

1. Go to Connectors, open the APIs tab, and choose Google Workspace.

2. Choose who signs in:

   • OAuth (Workspace-level): one Google account is connected and shared with everyone you give access to.
   • OAuth (Per-member): each member who uses the connector signs in with their own Google account.

3. Set each kind of access to Off, Read, or Read & write:

   Access	Read requests	Read & write also requests	What write unlocks
   Gmail	gmail.readonly	Not available
   Google Calendar	calendar.readonly	calendar.events	Creating, updating and cancelling events
   Drive, Sheets and Docs	drive.readonly	spreadsheets, documents	Writing cells in Sheets, adding rows, and adding text to Docs

   Only the access you enable is requested, so you can connect calendar alone without granting mailbox or Drive access. Turning on more access later takes effect after the account signs in again. Read & write cannot be combined with Metadata only.

4. Optionally enable Metadata only (see Privacy).

5. Click Connect, sign in, and review the consent screen.

6. Click Save.

The connector is private to you until you share it from the APIs tab. With workspace-level sign-in, everyone you share it with reads the connected account, so share it only with people who should see that mailbox.

Using it

Ask normally in any chat that can use API connectors. It composes with your warehouse and BI connectors, so questions can span both.

"What did Finance send me about the Q3 budget?"
"How many hours of meetings did I have last week, broken down by team?"
"Find the pricing model spreadsheet and pull the unit economics tab"
"Compare the pipeline in Snowflake to the forecast doc in Drive"

Search results are loaded into the Python sandbox as DataFrames, so aggregate questions about mail volume, meeting load and document activity are answered with real computation rather than by eyeballing a list.

You can also paste a Google Drive, Docs or Sheets link and Ana opens that file directly. For anything the built-in search and read steps don’t cover, Ana can call the Google APIs from Python with the same sign-in. Code can only read: every change goes through the approval described below.

Making changes

When the connector allows Read & write, each person chooses what Ana may change when they click Connect: Google Calendar, Google Sheets and Google Docs are separate choices, and only the ones chosen are requested from Google. Nothing is selected by default, so an account stays read-only unless its owner allows changes. You can change your choice at any time with Change next to your connection on the APIs tab.

When you ask for a change, such as “add the renewal call to my calendar for Thursday at 2” or “mark Acme as won in the pipeline sheet”, Ana shows a card with exactly what will change:

• For events: the title, time, guests and whether a video meeting is added. Guests are notified when the change is made.
• For Sheets: the cells being written, with the current value under each changed cell, or the rows being added.
• For Docs: the text being added to the end of the document.

Nothing happens until you click Approve. Decline, or sending another message instead, leaves everything as it was. If the cells changed after the card was shown, the change is not made and Ana is told to look again. If your sign-in does not allow that kind of change, for example a Sheets edit when you allowed only Docs, the card offers Allow changes, which signs you in again adding just that access and then asks for approval as usual.

To skip the card in a chat, turn on Auto-approve workspace changes in the chat’s tools menu. Ana then makes changes your sign-in allows right away and shows what it changed. It is off by default and applies only to chats you started yourself, not to chats with an agent or to messages others send in a chat you shared. Changes are only proposed in the app, with a person present. Scheduled runs, automated runs, Slack and Teams cannot make changes. Every approved change is recorded in the audit log.

If you turn off Gmail, Calendar or Drive after signing in, Ana stops calling the Google APIs from code for that account, because Google keeps the earlier permissions on the sign-in. To use it from code again, remove the app under Third-party apps & services in your Google account and sign in again.

Shared drives

Drive searches cover My Drive, shared drives and files shared with you. Each result carries the drive it came from.

Google Sheets

Spreadsheets are read through the Sheets API, so each worksheet arrives as its own DataFrame with its grid intact.

Privacy

Metadata only mode restricts the connector to non-content fields. When it is on:

• Available: message and file ids, sender and recipient addresses, timestamps, read and attachment flags, file sizes and types, event times and durations.
• Withheld: subjects, message bodies, file names, file contents, event titles, locations and attendee lists.

Content is never requested from Google in this mode, not merely filtered after the fact. Ana also cannot call the Google APIs from code with a metadata-only account.

Troubleshooting

The agent says the sign-in has expired

The stored grant is no longer valid. Common causes: you changed your Google password, a Workspace administrator revoked third-party app access, you removed TextQL from your Google account permissions, or the grant sat unused for six months. Open the connector on the APIs tab and click Connect to sign in again. The connector keeps its id, so chats and agents referencing it keep working.

This app is blocked by your organization

Your Google Workspace administrator restricts which third-party apps may request Gmail and Drive scopes. Ask them to allow the TextQL application, or connect only Calendar, which is not a restricted scope.

Reconnect needed

An admin changed what the connector can access after you connected. Click Reconnect next to the connector on the APIs tab to sign in with the new access.

The agent says changes are not allowed

The connector is set to Read for that kind of data. Ask an admin to set it to Read & write in the connector’s settings.

The agent says access is not enabled

Sign-in succeeded but a scope was not granted, usually because it was unchecked on the consent screen. Sign in again and accept all the requested permissions, or turn that access off.

A Drive file cannot be found by id

File ids expire when a file is moved to a different drive or deleted. Re-run the document search to get a current id.

Searches feel incomplete

Results are bounded so a single question cannot pull an entire mailbox or drive. When more matched than were returned, the agent is told the result was truncated and should say so. Narrow the date range or add filters for full coverage.