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.idasLOOKUP_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
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.
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.
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.
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
- Customer A receives only their permitted contact information.
- Asking for Customer B’s ID/email or sending a later-turn
variablesoverride cannot change the backend-authorized record; test both the proxy and agent result. - A missing mapping, invalid token or 404 follows the general-help/error path without creating a contact.
- 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.