> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery integration

> Use Voiceflow with Google BigQuery to answer customer questions from a curated view of account plans, service tiers and open-case counts.

## Overview

Use Voiceflow with Google BigQuery to answer customer questions from a curated view of account plans, service tiers and open-case counts. Your context service runs a bounded GoogleSQL query and returns only the current customer’s approved fields.

- Read the signed-in customer’s plan and support tier before explaining their service options.
- Use an approved open-case count to give context without exposing raw staff notes.
- Check the source refresh timestamp before presenting warehouse data as current.

The developer hosts the context service and maintains its provider access. The application authenticates the customer; a typed email or customer ID is not authorization. Runtime reads and Knowledge ingestion use separate workflows.

#### Studio

Use a project you can edit, a data owner and an application developer. Obtain a working service and test login before configuring the API tool below.

#### Developer

Use the runnable service recipe and Voiceflow API-tool APIs. Your backend owns customer identity, the provider principal and the runtime session; keep those credentials out of the browser.

<a id="connecting-bigquery"></a>

## Connecting Google BigQuery

Prepare the approved view and a working context service.

### Prepare provider access

1. Have the Google Cloud administrator select the query/billing project and dataset location, enable BigQuery access and provide a service identity. Use [Application Default Credentials](https://docs.cloud.google.com/bigquery/docs/authentication) on the service; on Google Cloud, attach the intended service account to its compute resource.
2. Grant `bigquery.jobs.create` on the query project and the necessary data access to the approved view. Ask the data owner to use an authorized view when the identity must not read the underlying tables directly. A query-project role alone grants no customer-table access.
3. Obtain `project.dataset.view`, the location and an approved `maximumBytesBilled` ceiling. Test [jobs.query](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query) under that identity and verify the billing project; the data and query projects can differ.

The data owner maps the approved view to this example contract. This is a deliberate customer-facing projection, not a copy of the raw customer table.

| View column | Meaning and required form |
| --- | --- |
| `tenant_id`, `customer_id` | Authorized application mapping; strings of letters, numbers, underscores or hyphens, at most 80 characters each. One row per pair. |
| `plan_name`, `support_tier` | Approved customer-visible strings, at most 80 characters. |
| `open_cases` | Nonnegative integer with the data owner’s agreed definition of an open case. |
| `last_synced_at` | UTC ISO 8601 text from the last completed source refresh. Do not substitute the query’s current time. |

The adapter uses GoogleSQL with named STRING parameters for tenant and customer, disables query caching and sets a byte ceiling. When `jobComplete` is false, it polls that job in the selected location. Errors, unfinished jobs or unexpected result pages do not become successful context.

### Prepare and connect the service

#### Studio

### 1. Obtain the developer’s tested service

Ask the application developer to deploy the provider-specific context service and authenticated runtime proxy described in the [service recipe](/docs/examples/data-storage/README.md). Have the credential owner create/populate the restricted **warehouse_context_service_token** Secret on the intended test Draft. Obtain the fixed HTTPS service origin, that Secret’s name, a test login and a successful intended-customer readiness check. In this Studio path, you create the variable and API tool in the next steps; the developer hands over the service and identity integration, not a second copy of those resources. The application supplies `warehouse_lookup_token` on every turn; do not collect it from the customer.

### 2. Create the protected variable

Open the project in [Agent studio](https://creator.voiceflow.com). In **More → Variables**, create `warehouse_lookup_token` with an empty default. The developer’s authenticated proxy must overwrite it for every launch, turn and supported resume while retaining runtime credentials server-side.

### 3. Configure the request

In **Agent → Global tools → + → API**, create **Read authorized customer context**. Select **POST**, use the supplied HTTPS origin plus `/v1/customer-context`, add `Authorization: Bearer {service_token}` and `Content-Type: application/json`. Set **Body → Raw → JSON** to `{"lookup_token":"{lookup_token}"}`.

Native API tool configured for the customer context service — Call the protected context service with a provided lookup token.

### 4. Bind the provided inputs

Save the request and open the attached tool’s **Input variables**. For **service_token**, choose **Default value → Secrets → warehouse_context_service_token**. For **lookup_token**, choose **Default value → Variables → warehouse_lookup_token**. Click outside to save, then reopen the rows to confirm the selected references. These inputs are provided values, not model-collected fields.

### 5. Check one authorized read

In the API editor’s **Run** panel, select the service Secret and paste a fresh, developer-issued test lookup token; attached defaults do not populate this test panel. Run once and require HTTP 200, `ok: true`, `found: true`, the intended `customer.customer_id` and a permitted `source_updated_at`. Compare the result with the data owner’s view before testing the conversation below.

#### Developer

Use Node.js 22 or later. Download the example files into an empty directory:

```sh
for file in package.json context.mjs providers.mjs server.mjs tool.mjs context.test.mjs providers.test.mjs README.md; do
  curl --fail --silent --show-error --remote-name \
    "https://www.voiceflow.com/docs/examples/data-storage/$file"
done
npm install
npm test
```

The tests are local contract fixtures. Configure these provider-specific values in the supervised service’s secret/environment configuration; replace every example resource with the administrator’s values:

```dotenv
WAREHOUSE_PROVIDER=bigquery
CONTEXT_VIEW=YOUR_DATA_PROJECT.cx.customer_context
BIGQUERY_PROJECT=YOUR_QUERY_PROJECT
BIGQUERY_LOCATION=US
BIGQUERY_MAX_BYTES=10000000
```

Also set `CONTEXT_TENANT_ID` to the fixed tenant, `CONTEXT_SERVICE_TOKEN` and `CONTEXT_SIGNING_KEY` to **different random server-only values**, and `CONTEXT_MAX_AGE_SECONDS` to your freshness policy (default 900). Generate each value separately with `crypto.randomBytes(32).toString('hex')`. The [service README](/docs/examples/data-storage/README.md) defines all configuration, deployment and result fields.

Run `node server.mjs` under your supervisor behind the existing HTTPS ingress. The default internal listener is `127.0.0.1:8080`; configure container binding/ingress deliberately. Your application must call `trustedContextTurn` from `context.mjs` behind its real sign-in middleware, using its server-authorized tenant/customer mapping on every launch, text turn and supported resume. That helper strips browser variables, state, identity and config. Keep runtime session credentials on the backend and prevent direct browser runtime access.

Set `SERVICE_ORIGIN`, `VF_TOKEN`, `PROJECT_ID` and `ENVIRONMENT` to your test resources. Use a [Voiceflow bearer credential](/docs/api-reference/authentication) with API-tool, Secret, variable, tool and compile permissions; keep it server-side. Create a restricted Secret **without a default value**, then set its explicit test Draft value:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"name":"warehouse_context_service_token","visibility":"restricted"}'
```

Retain `secret.id` as `SECRET_ID`. Prepare `secret-value.json` on your backend as `{"value":"YOUR_CONTEXT_SERVICE_TOKEN","environmentAlias":"YOUR_TEST_ALIAS","versionVariant":"draft"}` using your secret store’s value and the exact test Environment alias. These target fields belong in the request body. Keep it private and remove it after configuration:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @secret-value.json
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data '{"name":"warehouse_lookup_token","defaultValue":null,"color":"#515A63"}'
node tool.mjs "$SERVICE_ORIGIN" > tool.json
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @tool.json
```

Retain `apiTool.id` as `API_TOOL_ID`. Read `GET /v2/stable/api-tool-variable?apiToolID=$API_TOOL_ID&projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT` with the same bearer header. Match `variables[].name` to `id` for `service_token` and `lookup_token`. Those returned input IDs are needed for attachment.

Use `issueLookupToken` from `context.mjs` **on the backend** with the authorized test mapping, provider `bigquery` and signing key to create a fresh 120-second token. Save `inputs.json` with `{"inputs":{"service_token":"{warehouse_context_service_token}","lookup_token":"SIGNED_TEST_TOKEN"}}`, replacing only `SIGNED_TEST_TOKEN`. Execute the saved Draft:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @inputs.json
```

Require `success: true`, `error: null`, `truncated: false`, `output.status: 200`, `output.body.ok: true` and the intended `output.body.customer.customer_id` when `found` is true. A 200 with `found: false` means no matching context. Standalone execution does not attach or publish the tool.

<a id="reading-customer-context"></a>

## Reading customer context

Use the current authorized result in the customer’s conversation.

**Invocation:** Attach **Read authorized customer context** when the signed-in customer asks about their support plan or open-case count. The application provides the lookup token; the service provides the approved fields. The customer and model supply neither SQL nor a customer ID.

**Current result:** Answer only from the current successful result with `ok: true` and `found: true`. A missing customer, stale source or rejected lookup follows a general-help path without a claim about their plan. `fetched_at` records the request; `source_updated_at` records upstream freshness. A freshly executed query can still read stale source data.

**Conversation test:** Ask “What support does my plan include?” through the authenticated test application. Inspect the selected tool, provided inputs, returned customer/tier and the agent’s answer. Repeat for a second customer, a later-turn identity override, an expired token and a stale view; only the permitted current customer’s fresh context may appear.

### Attach and test the lookup

#### Studio

### 1. Describe when to use the tool

Open **Agent → Global tools → Read authorized customer context**. Set **Trigger** to “Read the signed-in customer’s support plan or open-case count when they ask.” Keep the two inputs bound to their provided Secret/variable references. Trigger text guides selection; the service enforces authorization.

### 2. Use the current result

In the agent’s instructions, tell it to answer from `customer.plan_name`, `customer.support_tier` and `customer.open_cases` only after a current successful lookup. On `found: false` or failure, explain that account context is unavailable and continue with general help. Do not interpret a tier name as a policy the data owner has not defined.

### 3. Run the customer journey

Use the developer’s authenticated application and the conversation test above. API-editor **Run** is a separate standalone check. Confirm the tool result and the actual customer answer before [publishing the reviewed Environment](/docs/documentation/deploy/environments/publishing).

#### Developer

After the standalone test, use `attachment` in `tool.mjs` with `API_TOOL_ID` and the two returned input IDs to write `attachment.json`:

```js
import fs from 'node:fs';
import { attachment } from './tool.mjs';
fs.writeFileSync('attachment.json', JSON.stringify(attachment({
  toolID: process.env.API_TOOL_ID,
  tokenInputID: process.env.TOKEN_INPUT_ID,
  lookupInputID: process.env.LOOKUP_INPUT_ID
})));
```

Save that script as `attach.mjs`, set both input-ID environment values, then run `node attach.mjs`. The attachment binds `service_token` to `{warehouse_context_service_token}` and `lookup_token` to `{warehouse_lookup_token}`, with both marked provided (`required: false`). Create the attachment:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @attachment.json
```

Resolve `unresolvedReferences` from the tool/resource creation and attachment responses before compiling. Then run:

```sh
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/environment/$ENVIRONMENT/compile?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Run the conversation test through your authenticated application. Keep its trusted mapping and fresh token on every forwarded turn/resume; the attachment default is not the access boundary. Inspect the actual invocation, current tool result and answer. Compilation does not publish. Before a reviewed Published agent is used, populate its explicit Published Secret target and verify that version’s lookup; the Draft value alone is insufficient.

For API-tool **Capture response**, paths begin in the service JSON: `ok`, `found`, `customer.plan_name`, `customer.support_tier` and `source_updated_at`. The standalone envelope adds `output.body`; do not include that prefix in a native capture path. Clear retained output variables before a new attempt when your workflow relies on them. Missing fields or a failed request can leave earlier values intact; an old plan or ID is not current success.

<a id="maintaining-data-access"></a>

## Maintaining data access

Keep authorization, source freshness and failure handling explicit.

The Google authentication library obtains current request credentials from ADC. The application owner must maintain the workload identity and view grants; an attached service account or impersonation configuration can be revoked independently. Investigate a location mismatch or byte-ceiling error before raising the query budget. Updating warehouse data is the data pipeline owner’s responsibility.

#### Studio

Have the application owner confirm rotation and freshness checks for the same project/Environment you test. If access is revoked or the service is unavailable, keep the general-help path active and stop presenting account-specific answers. Ask the data owner to inspect the source pipeline when `source_updated_at` is stale.

#### Developer

Monitor the service’s unavailable response, provider permission failures, credential expiry and source age without logging tokens or returned private rows. The service has a 10-second response deadline; a timeout does not prove the remote query stopped. Update the gateway service token in its server configuration and every deliberate Voiceflow Draft/Published Secret target together. Review [Secret version behavior](/docs/documentation/build/data/secrets#publishing-reverting-and-discarding-changes) after publish, revert or discard.

### Rotate and recheck the selected connection

### 1. Confirm the credential owner and target

Identify the service deployment, provider principal and the Voiceflow project/Environment using it. Have the owner check the provider-specific expiry and permissions above before changing any value. Keep provider credentials in the service’s secret store; only the context-service token belongs in Voiceflow.

### 2. Apply the reviewed credential change

#### Studio

Obtain confirmation from the service owner that the new provider credential is installed and the supervised service has reloaded. If the context-service token also changed, have the operator update the restricted Secret’s explicit Draft/Published targets. Do not paste a provider credential into the tool’s inputs.

#### Developer

Update the chosen provider’s server configuration and reload the supervised service. If rotating `CONTEXT_SERVICE_TOKEN`, use the Secret-value operation from the connection section with the same explicit Environment/version body fields, and install the matching value on the service. Keep the previous value’s consumers accounted for during the change; the signing key and provider credential are separate secrets.

### 3. Verify the current customer result after rotation

Issue a fresh signed test lookup token, run the saved request and require the intended customer ID, `ok: true`, `found: true` and permitted source timestamp. Then test the same authenticated conversation and a revoked/expired-token case. A working credential before rotation or an old retained response is not evidence that the new connection works.

### Diagnose missing or unavailable context

Separate authorization, source age and unfinished provider work.

- **401/403 from the context service:** verify the service Secret, signed lookup token, tenant/provider audience and its 120-second expiry. Obtain a fresh backend token for a new test.
- **200 with `found: false`:** inspect the authorized mapping and approved view; do not search other customer IDs or treat this as a default plan.
- **503:** the service rejects provider failures, duplicate identities, stale timestamps and incomplete results. Use controlled server-side diagnostics and the [Google BigQuery connection contract](https://docs.cloud.google.com/bigquery/docs/reference/rest/v2/jobs/getQueryResults); do not send driver errors or SQL to the customer.
- **Fresh request, old source:** repair or wait for the upstream refresh. Changing the fetch timestamp does not refresh customer data.

### Revoke access deliberately

Disable the lookup without changing customer data.

Remove or disable the attached tool, revoke the provider principal/token and stop the service under its owner’s control. Review the service-token Secret’s consumers before clearing values. This read-only recipe does not modify warehouse rows; stopping access does not delete data or imported Knowledge.
