Skip to navigation
Integrations

Google Workspace integration

Connect a Google account so that your Agents and Flows can use Gmail, Google Docs, and Google Sheets through tools. Add the tools to an Agent or to a prompt step in a Flow. The connection form also offers Calendar and Drive access, but no Runtype tool uses it. You do not need to select Calendar or Drive.

Before you begin

Prepare the following items before you connect Google Workspace:

  • A Google Cloud project that you can configure.
  • The Google APIs for the services that you plan to use.
  • An OAuth 2.0 client ID and client secret for a Web application.

Create an OAuth client

To connect Google Workspace, use your own Google Cloud OAuth client. Follow these steps:

  1. In the Google Cloud Console, create or select a project.
  2. Enable the API for each service that you plan to select: Gmail API, Google Calendar API, Google Docs API, Google Sheets API, or Google Drive API.
  3. Configure the OAuth consent screen. For a Google Workspace organization, select Internal. For other accounts, select External and add your account under Test users.
  4. Create an OAuth 2.0 client of type Web application.
  5. Add the Runtype redirect URI to Authorized redirect URIs. Use https://api.runtype.com/v1/oauth/google/callback. The connection form also shows this URI with a copy button.
  6. Save the client ID and client secret.

External apps in Testing mode receive refresh tokens that expire after 7 days. To avoid this limit, publish the app or use an Internal app. A published External app that requests Gmail, Docs, or Sheets access must pass Google app verification. In a Google Workspace organization, use an Internal app to skip verification.

Connect Google Workspace

In an organization, the Google connection is shared. Agents and Flows that any member runs act as the connected Google account. They send email from that account and read its inbox, Docs, and Sheets. We recommend that you connect a dedicated Google account for automation, not a personal account. For more information, see What are Organizations?.

To connect Google Workspace after you create the client, follow these steps:

  1. In Runtype, open Settings > Integrations.
  2. In the Google card, go to Connect a Google account.
  3. Select at least one service: Gmail, Calendar, Docs, Sheets, or Drive. Runtype requests only the scopes for the services that you select.
  4. If the form shows Use my own Google OAuth client, select it. The Client ID and Client secret fields appear.
  5. In Client ID, enter your Google Cloud OAuth client ID.
  6. In Client secret, enter your Google Cloud OAuth client secret.
  7. Click Connect Google.
  8. In the Google consent popup, approve the requested permissions.
  9. In the Google card, check that the connection lists every service that you selected. If a service is missing, follow the steps in Add a service to a connection and allow all requested permissions.

Runtype exchanges the authorization code and stores the tokens server-side. The tokens do not pass through your browser. Runtype does not store your Google password.

You can also connect Google from the tool picker. When you add a Google tool to an Agent or a prompt step and no account is connected, the tool picker shows a setup panel with the same fields and a Connect Google button.

Google tools use one connected Google account. If you connect more than one account, every Google tool call fails. Runtype has no option to remove a connection, so connect only one Google account.

Add a service to a connection

To add a service to an existing connection, use Connect another Google account in the Google card. Select every service that you need, including the extra service. If you use your own OAuth client, enter the client ID and client secret again, as in Connect Google Workspace. Sign in with the same Google account. Runtype updates the existing connection and does not create a second one. Reconnect does not add services, because it requests only the services that the connection already has.

Automatic refresh and reconnection

Runtype refreshes the access token before it expires. Google can revoke a refresh token if you remove the app from your Google Account or if the refresh token expires.

If the connection shows Needs reconnection, follow these steps:

  1. In Runtype, open Settings > Integrations.
  2. On the connection marked Needs reconnection, click Reconnect.
  3. In the Google consent popup, approve the requested permissions.

Reconnect requests the services that the connection already has and reuses your OAuth client. If Runtype cannot reuse the client, it shows an error. In that case, reconnect from the Google setup panel in the tool picker and enter the client ID and client secret again.

Available tools

After you connect, you can add the following tools to Agents and to prompt steps in Flows. The tools act on the connected Google account.

ServiceToolRequired parametersWhat it does
Gmailgmail_sendto, subject, bodySends an email right away. The body is HTML. Optional: cc and bcc as comma-separated addresses.
Gmailgmail_searchquerySearches with Gmail search operators and returns message IDs. Optional: max_results, from 1 to 100 (default 10). Use gmail_read for the content.
Gmailgmail_readmessage_idReads one email by its message ID.
Gmailgmail_create_draftto, subject, bodyCreates a draft. The body is HTML. Drafts have no cc or bcc.
Google Docsdocs_createtitleCreates an empty Google Doc. The tool ignores the content parameter.
Google Docsdocs_readdocument_idReads a Google Doc. The document ID is in the document URL.
Google Docsdocs_appenddocument_id, contentInserts text at the start of the document body, not at the end.
Google Sheetssheets_readspreadsheet_id, rangeReads cells in an A1 range, such as Sheet1!A1:D10. The spreadsheet ID is in the spreadsheet URL.
Google Sheetssheets_writespreadsheet_id, range, valuesOverwrites the range with an array of rows. Google evaluates values as typed input, so formulas are calculated.
Google Sheetssheets_createtitleCreates a Google Sheet. Optional: sheets, a list of tab names to create.

gmail_send sends email without confirmation. To review each message first, turn on Tool approval for gmail_send in the Agent, or use gmail_create_draft.

Permissions and scopes

Select only the services that your Agent or Flow needs. Runtype requests only the scopes for the services that you select. The following list describes the access that each service grants:

  • Gmail: read, send, and modify email, and create drafts.
  • Calendar: read and manage calendar events.
  • Docs: create, read, and edit documents.
  • Sheets: read, write, and create spreadsheets.
  • Drive: access files that the integration creates.

Troubleshooting

The following table lists common errors and how to fix them.

ErrorCauseFix
Google did not return a refresh token.Google did not issue a refresh token for this authorization.Remove the app at Google Account permissions, then connect again.
This Google authorization link has expired. Please restart setup.You waited too long before you approved the consent popup.Click Connect Google again.
Google authorization was denied.You canceled the Google consent screen.Connect again and approve the requested permissions.
Google Workspace is not connected.No Google account is connected.Connect a Google account in Settings > Integrations.
Your Google connection needs to be reauthorized.Google revoked the refresh token.Click Reconnect on the connection.
Multiple google integrations installedMore than one Google account is connected.Google tools work with one connected account only. Runtype has no option to remove a connection, so contact Runtype support.
Google API error (403)The API is not enabled in your Google Cloud project, or the service was not granted.Enable the matching API in the Google Cloud Console. If the connection does not list the service, connect again with that service selected.

Revoke Google access

Runtype has no option to disconnect Google. To revoke access, remove the app from your Google Account:

  1. Open Google Account permissions.
  2. In Third-party apps, find the app name that you set on your OAuth consent screen.
  3. Click Remove access.

After you remove access, Google tools fail. The connection shows Needs reconnection the next time Runtype tries to refresh the token.

Next steps