Documentation CRM Google Sheets

CRM integration

Google Sheets

Google Sheets integration overview
  • CategoryCRM
  • AuthService account
  • Scopes1

Overview

Google Sheets connects on /integrations in the dashboard through a bespoke multi-file flow (not the generic connect modal). MessageMind operates a shared Google service account; you grant it Editor access on each spreadsheet you want to connect, paste the sheet URL or ID into the Google Sheets card, and MessageMind proves the file is readable AND writable before storing it. One connection can hold many spreadsheets: add more, rename them, remove one and keep the rest, each managed independently. Once a sheet is connected, its tabs and row-1 headers become the column vocabulary available to triggers and actions, and MessageMind can enrol contacts from rows into automations, append new rows, or update named cells on existing rows.

What MessageMind can do with it

  • List the tabs of a connected spreadsheet and their row-1 headers for the step picker.
  • Enrol contacts from new or existing rows into an automation when a row carries an email or a phone.
  • Append one or more rows to a tab, creating any missing header column on the fly.
  • Update only the named cells of one or more existing rows, aligned to the row-1 headers.
  • Operate against the correct tab even after it is renamed, by tracking the tab's internal id in addition to its title.
  • Rename a connected spreadsheet's friendly name inside MessageMind without reconnecting the file.
  • Hold many spreadsheets on one connection, with per-file add, rename and remove in the same card.

Requirements

  • A Google account that can share a spreadsheet with a service account email.
  • The spreadsheet must be shared with the MessageMind service account as Editor. A Viewer-only share is accepted on the Google side but refused at Verify time, with the message to re-share as Editor.

How to connect

  1. In the MessageMind dashboard, open /integrations and click the Google Sheet card. The bespoke Google Sheets flow opens and fetches the service account email from the server.
  2. On the share step, click 'Copy email' to copy the service account address shown on the card (the button flips to 'Copied' for about a second).
  3. Open your Google Sheet in a new tab, click Share, paste the service account email and give it Editor access, then save the share.
  4. Back in MessageMind, paste the full Google Sheets URL or the spreadsheet ID into the input and click Verify. MessageMind calls POST /integration/google-sheet/verify, which proves the file can be opened, read AND edited by the service account.
  5. If verification passes, the detected sheet title is pre-filled as the friendly name (you can edit it) and the Connect button lights up. Click Connect; MessageMind calls POST /integration/google-sheet/connect, stores the spreadsheet against your tenant, and returns you to the manager with the new file in the list.
  6. To add another spreadsheet later, open the same Google Sheet card, click to add a file, and the share reminder plus the Verify / Connect pair runs again for that file.

Authentication and permissions

Mechanism
A single shared Google service account authenticated with its JWT private key, served under the Google Sheets scope. There is no OAuth flow on the user side; access is granted by sharing each spreadsheet with the service account email that the card copies for you.
Credentials
The service account's email and private key live on the MessageMind side. Per-tenant, MessageMind only stores the list of spreadsheets each user has connected (spreadsheet id and friendly name).

Required scopes

  • https://www.googleapis.com/auth/spreadsheets

Available data and actions

Reads

  • The spreadsheet's title and the list of tabs on it (up to the first 50 for header reads).
  • The row-1 headers of each tab, used as the column vocabulary for triggers and write actions.
  • The rows of a tab, with date-typed cells returned as formatted strings so column keys stay stable.
  • The spreadsheet's Drive-level last-modified timestamp, used to skip tabs that have not changed since the last poll.
  • A read + write probe at Verify time, so a file cannot be stored unless the service account can actually edit it.

Writes

  • New rows appended to a tab, inserted so blank rows further down are not disturbed.
  • Cell-level updates on named columns of one or more existing rows, with row-identity guards that skip a row the sheet has moved since it was last read.
  • Header cells, when a write mentions a column name that does not exist yet on row 1.
  • New columns at the right of the grid when the tab needs to be widened to fit a new header.

AI agent use cases

  • Treat a spreadsheet as the source of truth for new leads: a row with an email or a phone enrols that person into an automation.
  • Push conversation outcomes back into a tab, keeping the sheet in step with what the AI did without a human copying rows across.
  • Keep an existing row current (status, last message, booking link) by updating only the named cells of that row.
  • Connect several operational sheets (leads, bookings, follow-ups) under one Google Sheet card and route each to its own automation.

Configuration

  • Row scope for a Google Sheet trigger: all rows, or new rows only. New rows only takes a baseline of the identities present at connect time, so historical rows do not message anyone.
  • A new rows only trigger pins to a specific tab (by its internal id, so a rename still resolves). A configured tab that is deleted makes the trigger skip rather than fall back.
  • Headers are matched case-insensitively and trimmed, so Email and email are the same column. Creating a second header beside an existing one would permanently split one logical column.
  • Values are written as RAW, so a leading plus on a phone number or a leading equals on text is preserved verbatim rather than evaluated as a formula.
  • Each connected spreadsheet carries a friendly name you can change at any time through the card's rename action (PATCH /integration/google-sheet/sheets/:spreadsheetId); the Google file itself is untouched.

Example workflows

Connect a new spreadsheet

  1. You open the Google Sheet card. MessageMind fetches the service account email from GET /integration/google-sheet/service-account and shows it with a Copy email button.
  2. You share the spreadsheet with that email as Editor in Google Sheets, then paste the sheet URL or id and click Verify.
  3. MessageMind calls POST /integration/google-sheet/verify. It opens the file as the service account, proves read access, and probes write access. If read works but write does not, the card shows 'We can read this sheet but not write it. Give the service account Editor access, then verify again.' If the file cannot be opened at all, it shows 'We can't open this spreadsheet. Check the link and that it is shared with the service account.'
  4. On a passing verify, the detected title is pre-filled as the friendly name. You click Connect; MessageMind calls POST /integration/google-sheet/connect with the spreadsheet id and the chosen name and adds the file to your list.
  5. The manager refreshes to show the new file alongside any others; from there you can add another, rename, or remove without touching the connection itself.

Enrol new sheet rows into an automation

  1. A customer adds a row to a connected tab, with at least one of email or phone filled in.
  2. The sheet poll runs on its schedule and notices the spreadsheet changed since last pass.
  3. The row's email or phone is reconciled against existing contacts and upserted.
  4. The automation enrols the contact exactly once (two rows of the same person stay one enrolment, forever).
  5. The automation's first step runs and the conversation begins on the configured channel.

Limitations

  • Header reads for the tab picker cover only the first 50 tabs of a spreadsheet. Tabs beyond that are not surfaced for configuration.
  • A spreadsheet that is not shared with the service account as Editor is refused at Verify time, because the append and update actions would fail at run time.
  • New rows only requires a tab with an internal id. A tab without one is skipped (nothing is enrolled) rather than guessed.
  • Rows with neither email nor phone are skipped: there is no channel to message them and no stable key to deduplicate on.
  • The sheet poll runs on a five-minute cadence; a change that lands between passes is picked up on the next pass.
  • There is no user-side OAuth: access is bound to the shared service account email, so revoking that email in Google Sheets instantly severs MessageMind's access to that file.

Troubleshooting

Verify says 'We can't open this spreadsheet. Check the link and that it is shared with the service account.'

Open the sheet in Google Sheets, click Share, paste the service account email that the card shows (use the Copy email button) and give it access, then click Verify again. The same message covers a wrong link and an unshared file.

Verify says 'We can read this sheet but not write it. Give the service account Editor access, then verify again.'

The service account is on the share list as Viewer or Commenter. Change its role to Editor in the Google Sheets Share dialog and click Verify again. MessageMind will not store a file it cannot write to, because the append and update actions would fail later.

Clicking Connect fails with 'Connection failed, verify the sheet again.'

Something changed between Verify and Connect (the share was downgraded, or the same spreadsheet is already connected on this tenant). The card drops the Verified panel and routes you back to Verify so the current state is re-proven.

The file connected but the list still shows the old set, with 'Connected, but the list did not refresh. Close and reopen this window if it looks stale.'

The spreadsheet IS stored (Connect succeeded); only the refresh call after save failed. Close the Google Sheet card and reopen it and the new file will appear.

Removing a spreadsheet fails with 'Couldn't remove the spreadsheet.'

A transient server error stopped the delete. Try the trash action again; if it persists, reload the integrations page before retrying. Removing a file in MessageMind does not change the share on the Google file itself.

An update step reports that a row no longer matches.

The row has moved, been edited, or had its identifying column changed since the sheet was last read. The step leaves the row alone and reports it as skipped; the next run reads the fresh row.

Disconnect and reconnect

  • In the Google Sheet card, click the trash icon next to a connected spreadsheet to remove it (DELETE /integration/google-sheet/sheets/:spreadsheetId). The file is dropped from your list and no longer polled or available to automations; the Google Sheet itself and its share settings are untouched.
  • To fully sever MessageMind's access to a file, also open the sheet in Google Sheets and remove the service account email from the Share dialog. After that, any later read from MessageMind will fail and the file is skipped on the next pass.
  • To reconnect a spreadsheet, open the card, re-share with the service account as Editor if you removed it in Google, paste the URL or id again and run Verify / Connect; a fresh baseline is taken at that point.