Integrations / Google Sheets
Google Sheets
Value: Use CloudyBot in dashboard chat or on employees with the google_sheets skill to read and update spreadsheets through the official Sheets API v4—as long as your deployment’s one service account is allowed to access those files. Good for ops dashboards, lightweight CRMs, and recurring data pulls without building a custom Sheets client in every workflow.
How the integration is wired
The API keeps GOOGLE_SERVICE_ACCOUNT_JSON on the server (full service account JSON). There is no per-user Google OAuth for Sheets in this integration: every call uses that shared identity. Any user who can invoke the tools can pass any spreadsheet ID the service account can open—so access control is your Google sharing policy plus who you allow in CloudyBot.
Tools (skill id google_sheets, allowlisted in product code): read an A1 range; overwrite a range with a 2D array; append rows after a table in a range; get spreadsheet metadata (title, tab names). API base path is https://sheets.googleapis.com/v4/spreadsheets. The spreadsheet ID is the segment between /d/ and /edit in a Google Sheets link.
Operator setup checklist
- In Google Cloud, enable the Google Sheets API for the project.
- Create a service account, then create and download a JSON key.
- Set
GOOGLE_SERVICE_ACCOUNT_JSONon the API to the full JSON (single line in.env;private_keynewlines stay as\nwhen stringified, which matches the downloaded file shape). - In each Google Sheet, use Share and add the service account’s
client_email(Viewer vs Editor depends on whether you need writes). - Restart the API process after changing the variable.
- Optional check: authenticated
GET /api/sheets/statusreturnsconfigured: trueonly when the JSON parses and containsclient_emailandprivate_key—not whether a given sheet is shared.
Example workflows
- Read and summarize: Pull a bounded range (for example
Sheet1!A1:D50) and ask the model to summarize trends or flag outliers. - Append new rows: Append one or more rows to an existing table region (correct A1 append range matters—wrong range sends data to the wrong place).
- Overwrite a staging block: Replace a fixed range with fresh 2D values from a conversation. Tools accept optional
value_input_option:USER_ENTERED(default) orRAW. - Discover structure first: Call spreadsheet info to list tab titles before building range strings for read or write.
These are illustrative; the model only has the four tool actions above—not every Sheets UI feature.
Security and sharing
Shared service account: All CloudyBot users on the deployment share the same Google identity for Sheets. If two users both have google_sheets enabled, either could reference any spreadsheet ID that identity can access. Stricter per-user isolation would require a different auth model (not implemented here). Use a dedicated service account, only enable what you need, rotate keys if leaked, and do not log full JSON or access tokens.
FAQ
What can CloudyBot do with Google Sheets?
CloudyBot exposes first-party Google Sheets API v4 tools for dashboard chat and for AI employees that have the google_sheets skill: read cell values from an A1 range; overwrite a range with a 2D array of values; append rows after a table in a given range; and fetch spreadsheet metadata (title and sheet tab names). There is no separate Google Drive or Docs tool surface in this integration—only what those Sheets actions cover.
How does Google Sheets connect to CloudyBot?
The operator configures a single service account JSON on the API server as GOOGLE_SERVICE_ACCOUNT_JSON. The server builds a short-lived JWT signed with the private key, exchanges it at Google’s token endpoint for an access token, and calls Sheets v4. There is no per-user OAuth: you do not paste a personal Google token into CloudyBot for Sheets. You must share each spreadsheet with the service account client_email from that JSON (Viewer or Editor as needed). Restart the API after changing the env.
What does configured true on /api/sheets/status mean?
GET /api/sheets/status returns whether GOOGLE_SERVICE_ACCOUNT_JSON parses and includes client_email and private_key so the server can obtain tokens. configured true does not mean any particular spreadsheet is shared with the service account; Google can still return 403 or 404 if the sheet ID is wrong or not shared.
Why might I see 403, PERMISSION_DENIED, 404, or invalid private key errors?
403 or PERMISSION_DENIED often means the spreadsheet is not shared with the service account email, or the Google Sheets API is disabled for the Cloud project. 404 usually means the spreadsheet_id in the URL is wrong. Invalid service account private key often means the JSON in .env is malformed—typically newlines inside private_key must stay escaped as \n when the JSON is inlined. Append writing to the wrong place is often a wrong A1 range for append (for example Sheet1!A:Z).
Use it in the product once your operator has configured the service account. Open the dashboard to chat or configure employees with the Google Sheets skill.
Open dashboard