Identifying logged-in users

If visitors are logged in to your app, you can tell the widget who they are. The agent then knows their name, plan, and account age — and anything you hand it through custom attributes.

The identify call

Once the widget has loaded, call:

window.HelpShelf.identify({
  userId: 'user_1234',
  email: 'ada@example.com',
  name: 'Ada Lovelace',
  plan: 'pro',
  createdAt: '2025-03-14T00:00:00Z',
  customAttributes: {
    seats: 12,
    trialEndsAt: '2026-08-01',
    isAdmin: true,
  },
})

Every field is optional. Pass what you have.

Custom attribute values must be strings, numbers, or booleans.

Calling it before the widget loads

You don't need to wait. Calls made before the widget finishes initialising are queued and replayed once it's ready, so you can call identify() immediately after your own auth resolves.

Both window.HelpShelf and window.helpshelf work — they're the same object.

What it's used for

• The agent can address the user by name and reason about their plan.
• Escalations to a human arrive with the user's identity attached, so your team isn't asking "who am I talking to?"
• Live chat providers that support user identity receive it when the visitor escalates.

What not to pass

Don't put secrets in here. identify() runs in the browser, so anything you pass is visible to the user. Pass an opaque userId, not a session token; pass plan, not a payment method.

Other methods on the widget API

window.HelpShelf.open()              // open the panel
window.HelpShelf.close()             // close it
window.HelpShelf.toggle()            // toggle it
window.HelpShelf.search('refunds')   // open and run a search

These are handy for wiring your own "Need help?" links to the widget. See Controlling the widget from your own code.