Build with

Overview

Voiceflow’s Google Sheets integration reads ranges, appends request rows, updates cells and creates spreadsheets in the connected Google account. Use its built-in actions for operational logs and approved lookup data; no separately copied Google access token is needed.

Runtime reads do not import a spreadsheet into Voiceflow Knowledge. Use the separate data-source workflow for ingestion and verify its own refresh behavior.

Connecting Google Sheets

Authorize the intended project account and prepare controlled actions.

Use a project you can edit and a provider account approved for the selected data. OAuth authorizes the connected account; it does not authenticate the customer chatting with the agent. Connections belong to the project, so changing environmentAlias does not independently isolate a provider account. Use a dedicated test project when testing a different account.

Authorize and discover actions

Studio

1

Authorize the account

In Agent studio, select a dedicated test project. Open More → Integrations → Google Sheets → Connect, complete browser authorization and return to the intended account. Use a Google account with read access to the target file and edit access for writes. Workspace policy can require administrator approval.

Authorize the account that owns the data your agent will use. Photo:
2

Add the first read

Open Agent → Global tools → + → Google Sheets and select Get sheet. Set its Trigger to the approved lookup job and provide the fixed resource inputs. Keep protected customer identity supplied by your authenticated application.

3

Test the intended data

Use the action’s Run panel with explicit test values and compare the current result with the target base/file. Then run a conversation that needs the result. A Connected badge does not prove data access.

Code

Browser OAuth is required here too. Open Agent studio, select the project matching PROJECT_ID, then More → Integrations → Google Sheets → Connect. Authorize the intended account and return before running the commands. The generic integration-connect API does not replace OAuth.

Complete browser authorization before returning to code. Photo:

Set VF_TOKEN, PROJECT_ID and ENVIRONMENT for a project/test Environment you can access. Use a Voiceflow bearer credential with integration-read/execute permission and agent/tool/compile permission when attaching an action. Keep it on your backend. Discover the actual catalog before execution:

The schema supplies each toolName, inputs and integrationToolID when already added. A stored credential flag does not verify provider acceptance. Standalone execution uses the selected Environment’s saved Draft and the project’s Draft integration slot, with fallback to its Published slot.

Use actions in a customer conversation

For a read, attach the catalog action to Global tools or its owning Playbook and set Trigger to the concrete lookup. Use only the current returned data; no matches should ask for an appropriate next step without claiming that the customer has no account.

For writes involving customer text or a protected record, have the application developer validate the confirmed values and authorize identity on the backend. The input builders reject brace-shaped tokens and validate the example fields. JSON quoting and backslashes do not escape native variable/Secret binding. A Trigger is selection guidance, not an enforced confirmation or authorization gate.

In More → Variables, create these variables with empty defaults before binding them:

For another action, create each additional provided input variable before use and define its exact expected saved fields. The backend supplies the confirmed values; the Workflow owns result/readback/outcome variables. The developer supplies those values on every trusted interaction, sets approval to yes only for that server-recorded confirmed request, and clears it on other turns. Keep runtime credentials/session keys server-side and discard browser identity, state and variable overrides.

Build a Workflow with this sequence:

  1. Clear data_action_id and set data_action_outcome to not_run using Set at entry.
  2. Add a Condition requiring data_write_approved is yes. Its Else path returns to confirmation without executing the action.
  3. On the approved path, clear data_write_approved before the write, then use an Integration step with every input provided from the corresponding confirmed variable or approved resource value.
  4. Capture the current action’s ID/range using the paths below. Follow it with a Condition checking data_action_id is not empty, then the saved-field/readback check for that capability. Integration steps have no separate Failure path.
  5. Attach this Workflow to the agent for the customer job and keep the raw write action off Global/Playbook tools. Add both data_action_outcome and data_action_id as actual variable references in the agent’s instructions. Only data_action_outcome is verified plus the current result may produce a success answer; an ID retained after failed readback is insufficient.

Test a request with missing details, a confirmed request and a rejected action. Inspect the actual selected Workflow, provided inputs, current result and provider record; only the confirmed, verified action may be acknowledged.

Studio

Use the native Workflows, Set, Condition and Integration controls above. Create each provided variable before selecting it in an input’s Default value. Ask the developer to supply the validated values and recorded approval; a model-generated yes does not meet that prerequisite.

Code

For Code, create variables with POST /v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT and body {"name":"data_write_approved","defaultValue":null,"color":"#515A63"}; repeat for the result and each provided input. Use the same bearer header. Add the selected catalog action with POST /v1/stable/integration/google_sheets/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT and body {"toolName":"google_sheets_append_spreadsheet"}, retaining integrationToolID.

Download the guarded Workflow builder and sheets-workflow.config.json into the same directory. Add the readback action google_sheets_read_spreadsheet through the same catalog-tool API. In the configuration file, replace every RETURNED_... value with its returned resource ID and replace the example base/file with the owner’s resource. The source comments and keys identify the required approval, result, outcome and readback variable IDs; keep their names as created above. The expected values for all five fields and prepared array must be populated by your backend before the approved turn. Run:

Create workflow.json with the API below. The example compares all five submitted fields with the backend’s expected values; a current ID/range alone cannot pass verification. To configure another action, change its selected tool ID, exact inputs, capture path and complete readback checks; do not reuse append/create semantics for a different write. It produces the reset → approval → action → result-check graph above. Create that graph using POST /v1/stable/workflow?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT with the bearer header. Attach its returned workflow.id using POST /v2/stable/tool with body {"type":"workflow","workflowID":"RETURNED_WORKFLOW_ID","target":{"global":true},"description":"Run the confirmed data request and acknowledge only its current verified result."} and the same project/Environment query.

Expose the Workflow outcome in the caller’s instructions before compiling. Read the current text with GET /v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&includeInstructions=true and the same bearer header. Preserve agent.instructions; null starts with empty text, while an absent field requires another successful read. Append the following rule as actual variable references, then PATCH only instructions through /v2/stable/agent?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT with the same bearer header. includeInstructions belongs only on the GET:

Replace the preservation marker with the actual existing text using a JSON serializer; do not erase the agent’s other instructions or routing. Resolve unresolvedReferences after the PATCH. A Workflow tool returns its component name, so a static Trigger or attachment description does not expose these outcome values. Test a successful write followed by a failed readback: the new ID must not override unverified.

Resolve unresolvedReferences from earlier resource creation/attachment and instruction updates, then compile with PUT /v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID. Compile returns message and durationMs; it has no unresolved-reference field. Retain the agent’s existing tools and test the actual conversation through the trusted application. For a read-only direct attachment, use type integration, its returned integrationToolID, a target and inputVariables keyed by schema names; each input contains integrationToolVariableName, required and defaultValue. The tool contract owns the full lookup schema. Standalone execution alone does not attach, compile or publish anything.

Native Capture response starts inside the action’s data, using the paths below without a data or output prefix. Standalone responses add output.data. Clear retained results before a new attempt: failed actions or missing fields can leave old values unchanged.

Reconnect or stop account access

Change the connection deliberately without changing saved records.

In More → Integrations, inspect the intended connection before choosing reconnect/disconnect. Repeat browser OAuth and a controlled action after an account change. Review Published and Draft consumers before revoking access; stopping authorization does not delete records, spreadsheet rows or imported Knowledge. Do not disconnect automatically to address a schema or field error.

Reading spreadsheet values

Select an explicit range and preserve the meaning of its columns.

Supply the full https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/... URL as spreadsheetURL, not the bare ID. Use A1 notation for a range; quote sheet names with spaces, such as 'Support Requests'!A1:E10. The file URL and sheet tab name identify different resources.

Invocation: Attach the read tool when a customer asks about approved service information or an authorized request. The owner provides the file/range and column mapping; the application authorizes private customer access. Reading a whole shared sheet and asking the model to filter it is not an access boundary.

Current result: Interpret values against the agreed header order. Empty/trailing cells can be absent from returned arrays, so an array position is meaningful only within that mapping. A successful range read proves neither upstream freshness nor customer identity.

Get sheet

Studio

1

Choose Get sheet

For a read, use Agent → Global tools → + → Google Sheets → Get sheet. For a write, use the guarded Workflow from the connection section and select Get sheet in its Integration step. Keep raw write tools off the agent’s other tool lists.

2

Provide the exact inputs

Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.

3

Check the current outcome

Inspect values and range against the permitted file, columns and RequestKey. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.

Attach Get sheet with its file and range inputs marked as provided. Photo:

Code

Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:

Require success: true, error: null and truncated: false, then inspect values and range against the permitted file, columns and RequestKey. A transport-level 200 alone does not establish success.

Conversation test: Ask about a request visible in the test range and check the actual row and answer. Repeat with no match and a forbidden customer mapping; the agent must not use another row.

Use Get rows only for a sheet whose grid has at most 26 columns. For a wider grid, use Get sheet with an explicit range; the current row action’s last-column calculation does not encode multi-letter A1 columns.

Get rows

Studio

1

Choose Get rows

For a read, use Agent → Global tools → + → Google Sheets → Get rows. For a write, use the guarded Workflow from the connection section and select Get rows in its Integration step. Keep raw write tools off the agent’s other tool lists.

2

Provide the exact inputs

Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.

3

Check the current outcome

Compare the returned rowNumber, range and flat values with the intended row and RequestKey. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.

Code

Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:

Require success: true, error: null and truncated: false, then compare the returned rowNumber, range and flat values with the intended row and RequestKey. A transport-level 200 alone does not establish success.

Conversation test: Read the known test row, then move or insert a row and repeat the identity check. The row number alone must not be treated as a durable customer ID.

Recording support requests

Append a confirmed request and retain the range that was actually changed.

Prepare Requests with columns RequestKey, Name, Email, Topic, Status in that order. A values array contains rows, and each inner array follows that order; headers do not automatically map object fields to columns. The input builders produce the confirmed example values.

The illustrative confirmed request uses these values; replace them with the customer’s reviewed details. The backend prepares the full array and its expected readback values from the same validated request.

Invocation: Attach the guarded request Workflow when the customer confirms their support request. The customer supplies details; the application records confirmation, validates literal values and supplies a stable RequestKey and prepared array. Keep the file/range fixed to the approved team log.

Current result: Require updatedRows: 1, retain updatedRange and read that range to compare the RequestKey and saved values. Appending the same request again can create a second row; after a timeout, locate the stable RequestKey before deciding whether to retry.

Add to sheet

Studio

1

Choose Add to sheet

For a read, use Agent → Global tools → + → Google Sheets → Add to sheet. For a write, use the guarded Workflow from the connection section and select Add to sheet in its Integration step. Keep raw write tools off the agent’s other tool lists.

2

Provide the exact inputs

Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.

3

Check the current outcome

Capture updatedRange and inspect updatedRows/updatedColumns, then Get sheet for that returned range. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.

Bind the confirmed values array and capture the current updated range. Photo:

Code

Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:

Require success: true, error: null and truncated: false, then capture updatedRange and inspect updatedRows/updatedColumns, then Get sheet for that returned range. A transport-level 200 alone does not establish success.

Conversation test: Request account-access help, confirm the details and inspect exactly one correctly appended request row. Repeat with rejected edit access and verify that the agent reports no confirmed save.

Append uses Google’s logical-table detection within the supplied range and inserts rows after its last detected row. The append contract determines placement; Requests!A:E is not a promise to write at a specific numbered row. The connector writes RAW values with INSERT_ROWS: do not rely on automatic formula parsing or formatting conversion.

Updating existing cells

Verify the intended row before writing a bounded range.

Invocation: Use a guarded update Workflow only when the customer confirms an allowed change to the application-authorized request. The backend supplies the expected RequestKey, rechecked row/range and prepared values; the model must not choose an arbitrary cell range.

Current result: Require the returned range and row count, then read that same range and compare the saved value and RequestKey. A row number moves when rows are inserted, sorted or deleted. Read-before-write is not an atomic compare-and-set: use a controlled, serialized writer for concurrent edits or choose a store with the identity/update semantics the job requires.

Update sheet

Studio

1

Choose Update sheet

For a read, use Agent → Global tools → + → Google Sheets → Update sheet. For a write, use the guarded Workflow from the connection section and select Update sheet in its Integration step. Keep raw write tools off the agent’s other tool lists.

2

Provide the exact inputs

Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.

3

Check the current outcome

Compare updatedRange and updatedRows, then Get sheet for Requests!A2:E2 and verify the same RequestKey and Closed status. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.

Code

Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:

Require success: true, error: null and truncated: false, then compare updatedRange and updatedRows, then Get sheet for Requests!A2:E2 and verify the same RequestKey and Closed status. A transport-level 200 alone does not establish success.

Conversation test: Confirm a test request’s status change, recheck its row key and inspect the saved cell before acknowledging. An inserted row or mismatched key must stop the update.

Update writes RAW values into the specified cells; it does not append or match rows by a header/customer key. For this recipe, provide explicit string/number/boolean values. Google’s value-write contract distinguishes skipped nulls and empty strings that clear a cell; do not substitute either for an unchanged field without deciding that effect.

Creating a team spreadsheet

Create a new file and check its optional first-row headers.

Invocation: Keep this administrative tool with the setup workflow, outside an ordinary customer conversation. Run it when an authorized builder requests a new team log; the builder supplies the title and approved headers.

Current result: Retain spreadsheetId and spreadsheetUrl, open the new file and check its first tab and header row. A successful file creation followed by a failed header write can leave a real file; inspect the account before retrying creation.

Create new spreadsheet

Studio

1

Choose Create new spreadsheet

For a read, use Agent → Global tools → + → Google Sheets → Create new spreadsheet. For a write, use the guarded Workflow from the connection section and select Create new spreadsheet in its Integration step. Keep raw write tools off the agent’s other tool lists.

2

Provide the exact inputs

Use the input names and example below. Open each input row and bind its fixed resource or backend-prepared value through Default value; do not leave credentials, record identity or the whole JSON array to model selection. To test the individual action, enter the explicit sample in its Run panel; attached defaults and application variables are separate from test inputs.

3

Check the current outcome

Retain spreadsheetId and spreadsheetUrl and inspect Sheet1!A1:E1. Run the customer conversation through the appropriate application path and perform the test below before reporting completion.

Code

Save this illustrative request as action.json, replacing resource IDs and using backend-authorized, confirmed values before executing a write:

Require success: true, error: null and truncated: false, then retain spreadsheetId and spreadsheetUrl and inspect Sheet1!A1:E1. A transport-level 200 alone does not establish success.

Conversation test: As an authorized builder, request one test log, inspect the created file and headers, then confirm the tool is absent from the customer-facing agent’s tool list.

The first tab is Sheet1. Optional headers are written to Sheet1!A1 after creation. The returned key is spreadsheetUrl; existing-file actions require input spreadsheetURL. Share the file with the intended team separately; creation does not establish that another account can edit it.

Diagnose missing values or unexpected cell changes

Inspect file access, range identity and partial completion.
  • 403 or missing file: check the connected Google account, file sharing, edit permission and Workspace app policy.
  • Empty values: check the exact tab/range and whether cells are actually populated; do not replace missing private data with a different customer’s row.
  • Unexpected append location: inspect the logical table and returned updatedRange before repeating the request.
  • Rejected row range: check the Get rows grid-width limit above and prefer an explicit Get sheet range for wider sheets.
  • Create/header failure: look for the newly created file before creating another one.

Continue with the Data & storage Guides.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.