Build with

Overview

Use Voiceflow with Databricks SQL to answer account and support questions from a governed customer view. Your service runs a fixed query on an SQL warehouse and returns only the fields approved for the authenticated customer.

  • 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 Databricks SQL

Prepare the approved view and a working context service.

Prepare provider access

  1. Have the Databricks administrator assign a service principal to the AWS workspace, enable its required SQL entitlement and grant CAN USE on the selected SQL warehouse. Obtain the workspace origin and warehouse ID.
  2. Grant the principal USE CATALOG, USE SCHEMA and SELECT on the approved view in Unity Catalog. Keep raw-table and write permissions outside this read recipe.
  3. Create an OAuth M2M secret for that principal and store the client ID/secret on the service. Test workspace-level authorization and the Statement Execution API. This executable recipe uses an AWS workspace origin ending in cloud.databricks.com.

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.

For each lookup, the adapter obtains a workspace OAuth token using client credentials and all-apis, then submits a named-parameter statement with INLINE JSON results. It polls PENDING/RUNNING states and requires SUCCEEDED. Truncated or multi-chunk results fail the lookup. Warehouse permission and view grants still restrict what the principal can read.

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. 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. 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}"}.

Call the protected context service with a provided lookup token. Photo:
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.

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 databricks 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

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.

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 service requests a new workspace token for each lookup, so an expired access token is not stored in Voiceflow. The OAuth client secret still needs expiry monitoring and rotation. A stopped warehouse may need time to start; return an unavailable answer if the context-service deadline is exceeded. Do not treat PENDING, RUNNING or CLOSED as a usable completed result.

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

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.

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.

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 Databricks SQL 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.

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