Build with

Recognize a customer using the identity your application has authenticated. This walkthrough reads a HubSpot contact from an existing customer-to-CRM mapping and uses only the permitted profile fields. Matching a typed email is not authentication.

This is an additional API-tool lookup workflow. The built-in HubSpot and Salesforce catalogs do not expose a standalone contact-read action. Their connected CRM tools remain the path for the create/update operations they provide; use this recipe when the agent needs an independent profile read.

Before you begin

  • An application sign-in and trusted backend proxy that retains runtime session credentials and resets protected identity on every interaction, with a backend mapping from your customer ID to the intended HubSpot account and Contact ID.
  • The HubSpot contact lookup already configured in the same test project, including its separate read token and trusted identity binding. For Code, retain its apiTool.id as LOOKUP_TOOL_ID.
  • Two test customers with different CRM IDs and a policy describing which fields each may see. The examples use Maya Chen and Contact 1042; replace this illustrative ID with your own.

Studio

Open the project in Agent studio. In More → Variables, check that hubspot_contact_id exists with an empty default and is bound to the lookup input. Your backend must supply its authorized value on every interaction, strip client overrides and prevent direct browser runtime access. An initial binding is mutable and is not an access boundary.

Code

Use a Voiceflow bearer credential with access to this project and test Environment; keep it on your backend. Set VF_TOKEN, PROJECT_ID and ENVIRONMENT before using the commands. Standalone execution uses the Environment’s Draft. This API-tool lookup uses its separately provisioned provider token; connecting a built-in CRM action does not supply that token.

Recognize the customer

1

Resolve and authorize the CRM record

Use the authenticated application customer ID to retrieve the account and Contact ID from your backend. Check tenant/account and record access before passing that ID to Voiceflow. Reject missing or conflicting mappings; offer the general help path without exposing CRM data. Keep the runtime session ID separate. A browser holding a runtime session key can send later variable overrides: keep that key server-side, allowlist the customer action, discard client variables/state/identity and rebuild the CRM variable from the authenticated mapping for every forwarded turn or resume. The trustedCustomerTurn helper and tests show this boundary; integrate it behind your application sign-in.

2

Read only the permitted contact

Studio

Launch the conversation through your application with the verified hubspot_contact_id variable populated. Let Find HubSpot customer read that record. Use Run for a controlled test and inspect the actual ID, name and email in the tool result.

Keep the contact ID bound to identity verified by your application. Photo:

Code

Execute the prepared read tool using your backend-authorized ID:

Require success: true, no error/truncation, output.status: 200 and the authorized output.body.id. Read the allowed fields under output.body.properties. This call tests the tool alone; also exercise the actual authenticated agent conversation.

3

Use the profile without broadening access

Use the permitted display name or confirmed contact details for this customer’s request. Retain the CRM mapping for later authorized changes. Do not infer ticket, deal or company access from a Contact read. For Salesforce, use the Contact lookup, which returns Id, FirstName, Email and Phone with Salesforce field casing.

Verify customer isolation

  1. Customer A receives only their permitted contact information.
  2. Asking for Customer B’s ID/email or sending a later-turn variables override cannot change the backend-authorized record; test both the proxy and agent result.
  3. A missing mapping, invalid token or 404 follows the general-help/error path without creating a contact.
  4. The resulting agent answer matches the retrieved record and does not expose staff-only fields.

If the wrong record appears, inspect the authenticated mapping and input binding before reconnecting the CRM. A Trigger description alone cannot enforce access.

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