Description
We’re using HubSpot’s Visitor Identification v3 to identify users who are already authenticated in our own application. When a visitor is identified via the Visitor Identification token, HubSpot shows a badge in the conversations inbox UI indicating that the contact was successfully identified.
However, this “verified / identified via token” status is not exposed anywhere in the public APIs or webhooks for Conversations. From our webhook handler, we currently cannot distinguish:
- A visitor who was identified via a valid Visitor Identification token (i.e., truly authenticated in our system), vs.
- A visitor who simply typed an email address into the chat widget (non‑verified identity).
For security reasons, we only want to perform actions in our backend if the chat is coming from a user whose identity we can trust as authenticated (i.e., identified via Visitor Identification), not just anyone who knows or guesses an email address.
Current behavior / problem
- The inbox UI shows a badge when a visitor has been identified via the Visitor Identification API.
- Conversations webhooks and related APIs (threads, messages, contacts) do not expose a boolean/flag that tells us “this conversation/message comes from a visitor identified via a Visitor Identification token.”
- As a result, the Visitor Identification status is only usable for human agents in the UI, but not for secure, programmatic decision‑making in custom integrations.
This makes it difficult to safely “act on behalf of the user” based solely on chat traffic, even though Visitor Identification is meant to connect authenticated sessions with HubSpot chat.
Impact / use cases
- We want to trigger secure workflows in our backend from live chat (e.g., manage settings, trigger actions inside the user’s account) when the user is authenticated.
- Without a reliable, API‑level indication that the visitor was identified via our auth + Visitor Identification token, we cannot safely trust that the chat participant really owns that account.
- Today we must maintain extra mapping and logic on our side and still cannot be 100% certain based solely on HubSpot data.
Proposed solution
Please expose a “visitor identified via Visitor Identification token” flag in the Conversations data model, for example:
- A boolean field on the conversation/thread object (e.g. visitor_identified_via_token: true/false), and/or
- A boolean on each message sender/participant that indicates whether that participant is an identified visitor, and/or
- An explicit property on the associated contact or thread that marks that this conversation was initiated with a valid Visitor Identification token.
This flag should be available in:
- Conversations webhooks payloads
- Conversations APIs (threads, messages, etc.)
So that integrators can safely distinguish between verified and non‑verified visitors.
Why this matters
Visitor Identification is already designed around the idea that we have authenticated the user in our system and want to pass that identity through to HubSpot. Surfacing that same “verified” state in APIs/webhooks would make the feature truly useful for secure automation and backend integrations, not just for visual context in the inbox UI.