Google Drive

The Google Drive adapter lets nicoolAI read user-scoped Google Drive content after an explicit OAuth connection.

It is an adapter, not a channel.

That means it does not change where the conversation happens. It changes what the runtime can access on the user's behalf when a Google Drive, Docs, or Slides link appears in a supported flow.

Getting started

To get started with Google Drive, open the Google Drive connector setup, connect the Google account you want nicoolAI to use, and then share a supported Drive, Docs, or Slides link in web chat, WhatsApp, or Slack.

What it does

Today the adapter supports:

• Google Docs exported as plain text
• Google Slides exported as plain text
• Google Drive PDFs downloaded and ingested as document assets
• multiple named Google connections per user, such as personal and work

The current scope is read-only.

The runtime uses the Google account only to read supported files and turn them into bounded local artifacts that the conversation flow can reference.

For the product guide, the important point is simpler:

• Google Drive is the one live connector today
• it helps nicoolAI use shared documents without asking users to paste everything manually
• it stays narrow on purpose

Where it shows up

The adapter is currently used when Google Drive links appear in:

• dashboard web chat
• WhatsApp inbound messages
• Slack inbound messages

If the runtime can resolve a valid Google Drive connection for the user, it hydrates the link and attaches the resulting content to the conversation flow.

If it cannot, it creates a pending auth request and points the user to the Google Drive connect page.

What is supported

The supported file model is intentionally narrow.

Today, the connector is built around:

• Google Docs
• Google Slides
• Google Drive PDFs

Those formats show up in the runtime in a few different shapes depending on what the model needs.

Google Docs

Google Docs are exported as plain text and exposed as:

• a .gdoc handle for rendered-document access
• a .txt companion for plain text search and grep

Example:

• /gdrive/personal/Quarterly Plan.gdoc
• /gdrive/personal/Quarterly Plan.txt

Google Slides

Google Slides follow the same pattern:

• a .gslide handle for rendered or layout-aware access
• a .txt companion for plain text extraction

Example:

• /gdrive/personal/Board Review.gslide
• /gdrive/personal/Board Review.txt

PDFs

PDFs stay as document-style files and can be attached or read directly.

Example:

• /gdrive/personal/Deck.pdf

Important distinction:

• use .txt when you want plain text search
• use .gdoc, .gslide, or .pdf when formatting, layout, or rendered content matters

How it works across channels

Google Drive does not define its own conversation surface. It follows the channel where the link appears.

Web chat

In web chat, Google Drive links are resolved in the account-linked browser session.

If access is available:

• nicoolAI can hydrate the link immediately
• the mounted file context becomes available in the flow

If access is missing:

• the user is pointed to /dashboard/connect/google-drive

WhatsApp

In WhatsApp, Google Drive links are detected in the inbound message text.

If the WhatsApp sender can be resolved to a linked user with a Google Drive connection:

• nicoolAI hydrates the link and adds the resulting context to the message flow

If not:

• the runtime creates a pending auth request
• the user is pointed back to the Google Drive connect flow

Slack

In Slack, Google Drive links are processed inside the Slack conversation context.

That matters because connection resolution can consider:

• the current Slack workspace
• the current conversation or thread
• saved connection preferences

This is what lets the same user keep separate Google accounts and avoid using the wrong one by accident.

Connection flow

The user-facing entrypoint is the dashboard page at /dashboard/connect/google-drive.

The connection flow is:

1. The user chooses a connection name such as personal.
2. The app starts a Google OAuth flow with a signed state payload.
3. The callback verifies the signed-in user matches the OAuth state.
4. The adapter stores OAuth tokens as a user-scoped google-drive connection.
5. Any pending Google Drive auth requests for that user move from pending_auth to pending_hydration.

The callback now uses authenticated Convex writes instead of requiring the runtime key for a normal dashboard OAuth completion.

Named connections and resolution

Google Drive supports more than one connection per user.

This matters when the same person needs separate accounts, for example:

• personal
• client-a
• drio-work

Connection resolution follows this order:

1. an explicitly requested connection name
2. a saved preference for the current channel, Slack workspace, or thread
3. the only active connection, if exactly one exists
4. the connection named default, if present

If more than one active connection exists and no preference resolves the ambiguity, access fails closed and the runtime asks the user to choose a preferred connection.

Supported file handling

Supported Google file types are intentionally narrow.

Google Docs and Google Slides

Docs and Slides are exported as text/plain.

The adapter stores:

• a .txt artifact with the extracted text
• a .meta.json artifact with file metadata and source details

These artifacts are mounted under paths like:

• /gdrive/personal/Quarterly Plan.gdoc
• /gdrive/personal/Quarterly Plan.txt
• /gdrive/personal/Quarterly Plan.meta.json

PDFs

PDFs are downloaded as binary files and ingested through the asset pipeline.

The runtime keeps a mounted record for the file and attaches the resulting document asset to the conversation flow.

Unsupported files

Unsupported file types fail explicitly.

The adapter records the mount as failed and returns an unsupported_file_type result instead of pretending partial support exists.

Access model

The adapter is user-scoped and read-only.

Important properties:

• OAuth credentials are stored per user and per connection name
• runtime access checks resolve the connection through user identity, preferences, and granted capabilities
• missing or ambiguous access defaults to deny
• adapter resolution in runtime code goes through adapter and Google Drive runtime queries, not direct ad hoc checks

This keeps the Google Drive behavior aligned with the broader connector model: explicit connection, bounded capability, and fail-closed access.

Environment requirements

Google Drive OAuth requires these server-side settings:

• GOOGLE_DRIVE_CLIENT_ID
• GOOGLE_DRIVE_CLIENT_SECRET
• GOOGLE_DRIVE_REDIRECT_URI
• GOOGLE_DRIVE_OAUTH_STATE_SECRET or ADAPTER_SECRET_KEY

Runtime and background adapter access also require:

• ADAPTER_RUNTIME_KEY

That runtime key is still needed for non-user-session paths such as Slack, WhatsApp, and background processing.

Common failure modes

oauth_not_configured

Google OAuth env is missing or incomplete.

Check the Google Drive OAuth env variables first.

oauth_user_mismatch

The signed-in user completing the callback does not match the user encoded in the OAuth state.

Restart the connection flow while signed into the intended account.

auth_required

The runtime found a Google Drive link, but no usable connection could be resolved for that user.

Connect Google Drive in the dashboard, or set a preferred connection if more than one account is active.

unsupported_file_type

The file is real, but the adapter does not currently support exporting or ingesting that Google file type.

Related pages

• Connectors
• WhatsApp channel
• Slack channel
• Web chat
• Troubleshooting
• Security
• Channels and integrations