Passing Visitor Identity Data Through the SDK

When the live chat widget is deployed on an authenticated web property, Support Portal can receive structured identity data about the visitor through the SDK. This enables the platform to associate conversations with known contacts, enrich the agent's sidebar with contextual information, and enforce identity verification through HMAC validation. For telecom self-service portals, government citizen accounts, or enterprise customer dashboards, passing identity data transforms the widget from an anonymous channel into an authenticated communication layer tied to your existing user directory.

Operational objective

Without identity data, every widget session is treated as a new anonymous visitor. Agents must ask for identifying details manually, and conversation history cannot persist across sessions. By transmitting identity data through the SDK, organizations achieve several operational outcomes: conversations are linked to a persistent contact record, returning visitors see their prior history, agents receive subscriber or account context before the first message, and HMAC validation prevents impersonation. In regulated environments — where audit trails require a verifiable link between a conversation and an authenticated user — SDK-level identity binding is a deployment requirement rather than an optional enhancement.

SDK readiness

Before calling any identity methods, the widget script must be fully loaded. The SDK exposes window.$chatwoot as the primary interface object, but it is only available after initialization completes. Listen for the chatwoot:ready event to ensure that all subsequent SDK calls execute reliably:

window.addEventListener("chatwoot:ready", function () {
  // window.$chatwoot is now available
});

All identity-related SDK calls described in this article — setUser, setCustomAttributes, and reset — must be invoked inside this event handler or after it has fired. Calling these methods before the SDK is ready will result in silent failures.

Identifying visitors with setUser

The setUser method binds the current widget session to a known identity. It accepts a unique identifier as the first argument and an object of profile fields as the second:

window.$chatwoot.setUser("subscriber-88421", {
  email: "[email protected]",
  name: "J. Müller",
  phone_number: "+49 170 555 0199",
  avatar_url: "https://portal.example.gov/avatars/88421.png",
});

The unique identifier (first argument) should be a stable value from your user directory — a database primary key, subscriber ID, or account reference number. Support Portal uses this identifier to match the session to an existing contact record or create a new one.

Available profile fields

The following fields are supported in the profile object passed to setUser:

All fields are optional. Only fields with non-empty values are written to the contact record.

Enterprise example: telecom subscriber identification

In a telecom self-service portal, the authenticated session typically contains subscriber metadata. Passing this data through setUser allows agents to see the subscriber's plan, region, and account status before the conversation begins:

window.addEventListener("chatwoot:ready", function () {
  window.$chatwoot.setUser(currentUser.subscriberId, {
    email: currentUser.email,
    name: currentUser.displayName,
    phone_number: currentUser.msisdn,
    company_name: "Residential",
    description: "Fiber 100 — Active since 2021",
    country_code: "NL",
    city: currentUser.serviceCity,
  });
});

This pattern eliminates the need for the pre-chat form on authenticated portals, since the identity is already established by the host application's session.

Identity verification with HMAC

In production deployments, passing identity data without verification allows any client-side script to impersonate a user by supplying a fabricated identifier. HMAC-based identity validation prevents this by requiring a server-generated signature alongside each setUser call.

The identifier_hash field carries an HMAC-SHA256 signature computed on your backend using the widget's HMAC token (available in the inbox configuration) and the user's unique identifier:

window.$chatwoot.setUser("subscriber-88421", {
  name: "J. Müller",
  email: "[email protected]",
  identifier_hash: "a]5f2c...server-generated-hmac-hash",
  phone_number: "+49 170 555 0199",
});

When identifier_hash is present, Support Portal validates the signature before accepting the identity binding. If the hash does not match, the session is treated as unverified. Enabling HMAC validation also activates conversation history persistence — authenticated visitors returning to the site will see their previous conversations.

For details on generating the HMAC token and implementing server-side signature logic, see Identity Validation via HMAC Verification.

In regulated environments — government portals handling citizen data, telecom operators subject to identity verification mandates — HMAC validation is strongly recommended. It provides a cryptographic guarantee that the identity presented to agents matches the authenticated session on the host application.

Full setUser call with HMAC and social profiles

The following example demonstrates a comprehensive setUser invocation that includes identity verification, demographic fields, and social profile links:

window.$chatwoot.setUser("acct-2947-eu", {
  name: "Elisa Korhonen",
  email: "[email protected]",
  identifier_hash: "b8d91e...server-generated-hmac",
  phone_number: "+358 50 123 4567",
  description: "Enterprise contract — Platinum SLA",
  company_name: "Nordic Logistics Oy",
  country_code: "FI",
  city: "Helsinki",
  avatar_url: "https://portal.enterprise.fi/photos/2947.jpg",
  social_profiles: {
    linkedin: "elisakorhonen",
    twitter: "e_korhonen",
  },
});

Setting custom attributes

Beyond the standard profile fields, your deployment may need to surface domain-specific data in the agent's sidebar — contract tier, device model, subscription status, or internal case reference numbers. The setCustomAttributes method attaches arbitrary key-value pairs to the current conversation's contact record:

window.$chatwoot.setCustomAttributes({
  subscriptionTier: "Enterprise",
  contractId: "CT-2024-88421",
  deviceModel: "Nokia XR30",
  provisioningRegion: "EU-West",
});

Custom attribute keys must correspond to attributes defined in Settings > Custom Attributes. If a key does not match an existing custom attribute definition, it will still appear as a conversation-level attribute but will not be indexed or filterable. See Custom Attributes for guidance on defining custom attributes in the platform.

Custom attributes support String, Number, and Date value types. The type must match the definition configured in the platform — passing a string value to a number-type attribute will result in a type mismatch.

Removing a custom attribute

To remove a specific custom attribute from the current contact, use the deleteCustomAttribute method with the attribute key:

window.$chatwoot.deleteCustomAttribute("provisioningRegion");

This is useful when session context changes — for example, when a subscriber navigates from a device management section to a billing section and the device-specific attributes are no longer relevant.

When to call setUser

The timing of the setUser call depends on your application's authentication flow.

On page load (authenticated portals) — If the host application requires authentication before the user reaches the page with the widget, call setUser immediately inside the chatwoot:ready handler. This is the most common pattern for enterprise and government portals where the session is already established.

After login (single-page applications) — In applications where authentication occurs after the initial page load — such as SPAs with deferred login flows — call setUser after the authentication callback completes. The widget will transition from an anonymous session to an identified one without requiring a page reload.

Conditional identification — Some deployments intentionally allow anonymous browsing with the option to identify later. In this pattern, the widget loads without identity data, and setUser is called only when the visitor explicitly signs in or provides identifying information through the application's own UI.

In all cases, setUser should be called only once per session. Calling it multiple times with different identifiers within the same page lifecycle may produce unpredictable contact matching behavior.

Resetting the session

When a visitor signs out of your application, the widget session must be reset to prevent the next user on the same device from inheriting the previous visitor's identity and conversation history. Call the reset method as part of your application's logout flow:

window.$chatwoot.reset();

This clears the identity binding, removes any custom attributes associated with the session, and returns the widget to an anonymous state. If a new user subsequently signs in, a fresh setUser call establishes the new identity.

Failing to reset on logout is a data hygiene risk, particularly in shared-device environments common in government offices, retail locations, and call center workstations. In these contexts, the reset call should be treated as mandatory rather than optional.

Listening for widget events

The SDK emits events that can be used to coordinate identity data transmission with widget activity. Beyond the chatwoot:ready event (required before any SDK call), the following events support operational monitoring:

Message events — To capture inbound messages from the widget for logging or analytics integration:

window.addEventListener("chatwoot:on-message", function (e) {
  console.log("Message received:", e.detail);
});

Error events — To detect and log widget-level errors during operation:

window.addEventListener("chatwoot:error", function (e) {
  // Forward to your application's error tracking service
});

These event listeners are independent of identity data but are frequently deployed alongside setUser as part of a comprehensive SDK integration.

Deployment checklist

Before promoting an identity-enabled widget deployment to production, verify the following:

• The setUser call executes inside the chatwoot:ready handler or after the event has fired.
• The unique identifier used in setUser is stable and does not change across sessions for the same user.
• HMAC identity validation is enabled and the identifier_hash is generated server-side — never expose the HMAC token in client-side code.
• Custom attribute keys passed to setCustomAttributes match definitions in Settings > Custom Attributes.
• The reset method is called on user logout, particularly in shared-device environments.
• Widget error events are monitored in production to detect silent failures in identity binding.

For widget configuration options beyond identity data — including visual customization, dark mode, business hours, and pre-chat forms — see Live Chat Widget Configuration.