Add or find rows in Google Sheets

A Google Sheets step in a flow does one of two things with a worksheet you choose:

• Add a row — for example, log every new lead with their handle, email and the date.
• Find a row — look the person up by a column (their handle, their email) and use what's in that row later in the flow, like a discount code or a VIP tier.

Where it's on: Google Sheets steps are being turned on workspace by workspace. If Settings → Channels has a Google Sheets card and the flow builder offers a Google Sheets step, it's on for yours.

Who can do what: owners and admins connect and disconnect the Google account. Owners, admins and agents set up, test and read the results of Google Sheets steps. See roles-and-permissions.md.

Connect your Google account

1. Go to Settings → Channels and find the Google Sheets card.
2. Click Connect Google Sheets and sign in to Google.
3. On Google's screen, leave See, edit, create and delete only the specific Google Drive files you use with this app ticked, and click Continue.

The card now says Connected as your Google address. HyperDM can open only the spreadsheets you choose on a step — not the rest of your Drive. One Google account per workspace.

Add a Google Sheets step

1. Open a flow and Save it — a step can only be set up on a saved flow.
2. From Add step → Advanced steps, add Google Sheets.
3. In the step's panel, click Set up.
4. Click Choose with Google, and pick the spreadsheet. Choose it while signed in to Google as the account shown on the Settings card — a spreadsheet picked with a different account can't be opened.
5. Choose the Worksheet and the Header row (the row with your column names), then click Read columns.
6. Under What this step does, choose Add a row or Find a row.

Add a row for each person

1. For each column, choose what it receives: a contact field like {{email}}, a contact detail like {{username}}, a value an earlier Google Sheets step found, the date of the run, or Fixed text…. Leave a column on Don't write this column to skip it.
2. Choose each value's type — Text, Number, Yes / no or Date.
3. Choose How values are stored:
   • Exactly as sent (recommended) — what the person wrote is stored as-is. Anything that looks like a formula stays text and never runs.
   • As if typed into Google Sheets — numbers and dates in text are recognised; anything that would start a formula is kept as text.
4. Under Record a run key, pick an empty column if you have one. If Google ever doesn't confirm a row was added, HyperDM looks for that key before trying again, so the row is never added twice.

The step has two branches: Row added and Didn't work.

Find a row and use what's in it

1. Search the column — the column that identifies the person, like Instagram handle.
2. For the value — what to search for, like {{username}}. A match is the same text, ignoring capital letters and extra spaces. An empty value never matches.
3. When more than one row matches — you must choose: Use the first matching row, Use the last matching row, or Take the “More than one match” branch.
4. Under Keep values from the row, tick the columns you want to use and give each a name. Use them later in this run as {{sheet.tier}} in a message, or sheet.tier in a Condition.

The step's branches: Found, No match, More than one match (only if you chose it) and Didn't work. On any branch but Found, the kept values are empty — never a previous person's.

Test before you save

1. Under Test, check the test values (they're pretend — nothing is sent to anyone).
2. For Add a row, click Preview the row to see exactly what would be written. Nothing is written yet.
3. To really add it, click Add this test row…, read where it will go, then click Add 1 row to your spreadsheet › tab. Delete that row in Google Sheets afterwards.
4. For Find a row, click Look it up to see the value searched for, which branch a run would take, and the values found.
5. Click Save step. HyperDM checks the worksheet one more time and saves only if every column is where you mapped it. Then Save the flow.

If saving fails, everything you chose stays in the dialog, with the reason.

Check how the step is doing

Open the step and expand Run results: each recent run and test, what happened, the row number, how many attempts it took, and Google's own message when something went wrong.

If Google didn't confirm a row was added and there's no run key column, the result says Needs checking. Look in the sheet, then click The row is there or It isn't there.

When a step needs review

A step shows Needs review, and takes its Didn't work branch, when:

• a mapped column was renamed, deleted, or its name now appears twice — the panel says which;
• the worksheet was deleted;
• the connected Google account can't open the spreadsheet any more;
• Google Sheets was reconnected with a different Google account.

A column that only moved (say, a new column was inserted before it) is followed automatically. To fix a step, click Review setup, choose again or click Read columns again, and Save step.

If Google stops accepting HyperDM's access

If you remove HyperDM from your Google account's permissions, or Google stops accepting the access, the Settings card says Reconnect needed and every Google Sheets step takes its Didn't work branch. Click Reconnect on the card.

When Google asks HyperDM to slow down or is briefly unavailable, a step waits and tries again — up to three more times, at least 1, 5 and 15 minutes apart — before taking Didn't work.

What Google Sheets steps don't do

• They don't update or delete rows, or create new spreadsheets.
• A Find a row step searches at most 10,000 rows; a bigger sheet is refused rather than searched in part.
• They can't be set live until they're set up, the Google account is connected, and nothing needs review.
• A flow copied, shared or imported from elsewhere keeps its Google Sheets steps but not their spreadsheets — set each one up again. A step copied inside a flow offers Copy the original's setup.