Google Drive
Connect Google Drive to let Helios agents read, upload, and organize files within the permissions you grant, and to start agents when files, folders or shared drives change.
What your agents can do
Agents use your connected Google account to work with files and folders, within the permissions you grant.
- Search and list files and folders across your Drive
- Read file metadata and the content of text files
- Export Google Docs, Sheets and Slides as text or CSV
- Create folders, and upload text files such as reports or CSV exports
- Organize, copy, and update files the agent created or you opened with Helios
- Find Google Meet recordings and photos (read-only)
- Manage the hidden app-data folder
Agents can also download and upload binary files through the API tool.
Authentication
| Method | Type | Description |
|---|---|---|
| Helios Google Drive App | OAuth 2.0 | Sign in with Google through the Helios app (recommended) |
| BYO Google Drive App | OAuth 2.0 | Paste tokens that you create with your own Google OAuth client |
Helios Google Drive App
Helios runs the Google OAuth redirect flow and asks each user for consent (access_type=offline, prompt=consent) so agents can act on your behalf, including when you're offline.
The Helios Google Drive App requests scopes to:
- Read files and file metadata (
drive.readonly,drive.metadata,drive.metadata.readonly) - Create and manage files it opens with Helios (
drive.file) - Read Google Meet recordings and photos, read-only (
drive.meet.readonly,drive.photos.readonly) - Manage the hidden app-data folder and read installed-app metadata (
drive.appdata,drive.apps.readonly)
BYO Google Drive App
Use this method when you need your own OAuth client, for example for your own branding. Helios doesn't redirect to Google for this method. You create the tokens yourself and paste them in.
- In the Google Cloud console, create a project or pick one. Under APIs & Services → Library, enable the Google Drive API.
- Open Google Auth Platform. On Branding, set the app name and the user support email. On Audience, choose Internal, or External with your account under Test users.
- On Data Access, click Add or Remove Scopes and add the Drive scopes listed above. Each one is
https://www.googleapis.com/auth/plus its name, such ashttps://www.googleapis.com/auth/drive.readonly. - On Clients, click Create client and choose Web application. Under Authorized redirect URIs, add
https://developers.google.com/oauthplayground, then click Create. - Open the OAuth 2.0 Playground. Click the gear icon, tick Use your own OAuth credentials, enter the client ID and secret, and keep Access type set to Offline.
- In Step 1, enter the Drive scopes, click Authorize APIs, and approve access with the Google account the agent should use. In Step 2, click Exchange authorization code for tokens.
- In Helios, choose BYO Google Drive App. Fill in Client Id and Client Secret from your client, Access Token and Refresh Token from the Playground, and Email with the Google account you approved with.
Helios renews the access token with the refresh token. Google expires the refresh token of an External app in Testing 7 days after you approve it, so publish the app on the Audience page to keep the connection working. If the refresh token stops working, create new tokens in the Playground and enter them through Manage.
Learn more in the Google Drive API documentation.
Triggers
Google Drive can start a Workflow when files, folders or shared drives change. Helios sets up notifications with the Drive API when you save the connection, so there is nothing to set up in Google.
Google keeps a change log for each account and one for each shared drive. Helios watches the connected account's log, which covers My Drive and the files shared with you, and the log of every shared drive the account is a member of. When the account joins or leaves a shared drive, Helios starts or stops watching that drive within a few minutes.
| Event | Description | Filters |
|---|---|---|
file.created | A file or folder was created, uploaded or copied | name (pattern), MIME type (pattern), folder, shared drive |
file.updated | A file or folder changed, such as its content, its name, its folder or its sharing | name (pattern), MIME type (pattern), folder, shared drive |
file.trashed | A file or folder was moved to the trash | name (pattern), MIME type (pattern), folder, shared drive |
file.untrashed | A file or folder was restored from the trash | name (pattern), MIME type (pattern), folder, shared drive |
file.removed | A file or folder was deleted permanently, or the account lost access to it | shared drive |
shared_drive.added | You were added to a shared drive, or you created one | shared drive, shared drive name (pattern) |
shared_drive.updated | A shared drive changed, such as its name, its settings or its members | shared drive, shared drive name (pattern) |
shared_drive.removed | A shared drive was deleted, or you were removed from it | shared drive |
All filters are optional.
- Name matches the name of the file or folder. Case doesn't matter, so
*.pdfalso matchesSCAN.PDF. - MIME type matches the file's type, such as
application/pdforimage/*. Google's own files have their own types:application/vnd.google-apps.documentfor Docs,application/vnd.google-apps.spreadsheetfor Sheets,application/vnd.google-apps.presentationfor Slides andapplication/vnd.google-apps.folderfor folders. - Folder is chosen from a list of your folders. It matches files and folders directly inside the folder, not in its subfolders.
- Shared drive is chosen from the shared drives the account is a member of. Changes in My Drive don't match when it's set.
- Shared drive name matches the name of the shared drive. Case doesn't matter.
How Helios reads the changes:
- An event has the current state of the file, not what changed.
- A file counts as created when it was created after the last change Helios read. A file that someone created earlier and then shared with you, or moved into a shared drive, arrives as
file.updated. - Google also records changes that only affect your own view, such as starring a file or opening it for the first time. They arrive as
file.updated. - For
file.removed, Google sends only the file's ID. The name, MIME type and folder filters can't match it, and Google doesn't say whether the file was deleted or the account lost access.
Listing shared drives needs read access to your whole Drive (drive.readonly). Without it, Helios watches only the account's own change log. A connection that only has drive.file receives file events only for files that Helios created or that you opened with Helios.
An agent's own changes can start new runs. An agent that uploads a file to a watched folder starts another file.created run. Filter on the folder or the name, or say in the prompt which files to ignore. See Guarding against events you don't want.
Check that it works
- Add
file.createdto a workflow with no filters. - Upload a test file to My Drive.
- Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.
| What you see | Cause | Fix |
|---|---|---|
| Every Drive event shows as unavailable | The connection has no access to Google Drive | Click Re-connect and allow every permission Google asks for |
| Shared drive events show as unavailable | The connection can't list your shared drives | Click Re-connect and allow every permission Google asks for. For BYO Google Drive App, create tokens with drive.readonly |
| No run starts after a change | The filters don't match, the file is in a subfolder of the chosen folder, or the refresh token stopped working | Test with no filters, and click Re-connect if the connection shows Error |
Notes
Helios requests read access to your Drive plus write access to files it creates or you explicitly open with it (drive.file). It doesn't request the full drive or drive.scripts scopes, so content and sharing changes are limited to files created or opened with Helios. The drive.metadata scope also allows metadata changes, such as renaming and moving files, where the connected account has permission.
Last updated on
Google Docs
The Google Docs integration lets Helios agents search the Google Docs API and call any endpoint to create documents, edit content, and manage formatting.
Google Sheets
The Google Sheets integration lets Helios agents search the Google Sheets API and call any endpoint to create spreadsheets, read and write data, and manage formatting.