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.
Code
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.
Connecting Google BigQuery
Prepare the approved view and a working context service.
Prepare provider access
- 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 on the service; on Google Cloud, attach the intended service account to its compute resource.
- Grant
bigquery.jobs.createon 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. - Obtain
project.dataset.view, the location and an approvedmaximumBytesBilledceiling. Test 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.
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
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. 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.
Create the protected variable
Open the project in Agent studio. 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.
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}"}.
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.
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.
Code
Use Node.js 22 or later. Download the example files into an empty directory:
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:
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 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 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:
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:
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:
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.
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
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.
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.
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.
Code
After the standalone test, use attachment in tool.mjs with API_TOOL_ID and the two returned input IDs to write attachment.json:
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:
Resolve unresolvedReferences from the tool/resource creation and attachment responses before compiling. Then run:
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.
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.
Code
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 after publish, revert or discard.
Rotate and recheck the selected connection
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.
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.
Code
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.
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
- 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; 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.