Identify users and tenants with HelpAlive.identify()

HelpAlive.identify() is the call that tells HelpAlive who is signed in to your app. This page explains every field of identify() and when to call reset(), for the developer who installs HelpAlive. The agent appears only once identify() has run.

identify() at a glance

Call identify() right after login, and on every page load while the user stays signed in.
userId and displayName are always required. In a B2B app, tenantId and tenantName are required too.
role and plan are recommended, because the agent reads both.
No events are sent for a visitor until identify() runs.
Call reset() in your logout code, apart from your identify() call.

Prerequisites

The HelpAlive tag is in the head of every page. See Install the script.
You have decided which id to use for users and, if your app has them, for companies.

When to call identify()

Call it wherever your app already knows the signed-in user: right after login, and on every page load while they stay signed in. Calling it again with the same details is safe. Call it as early in each page load as you can. Keep these four lines above your first call. They let your code call HelpAlive before our script has finished loading, and our script replays the calls in order:

// Lets the calls below run before our script has finished loading. Keep it first.
window.HelpAlive = window.HelpAlive || { q: [] };
["identify", "reset", "setConsent", "track"].forEach((m) => {
  if (!HelpAlive[m]) HelpAlive[m] = (...args) => HelpAlive.q.push([m, args]);
});

The call

Pick the tab that matches your app. Settings → Setup & API Key shows the same two.

B2B: users belong to tenants
B2C: users have no tenant

Each customer company or workspace is a tenant, and its users sign in under it. tenantId and tenantName say which tenant each user belongs to. Some users have no tenant? Leave both out for them: your dashboard groups them as B2C customers.

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  tenantId: String(company.id), // required: their company or workspace
  tenantName: company.name,     // required: the company's name, shown in your dashboard
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  role: user.role,              // recommended, helps the agent
  plan: company.plan,           // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

Each user signs up on their own, with no company or workspace around them, so leave out tenantId and tenantName. Your dashboard groups them as B2C customers.

// On every page while someone is logged in, starting right after login
HelpAlive.identify({
  userId: String(user.id),      // required: your own id for this person
  displayName: user.name,       // required: the person's name (or their email), shown in your dashboard
  email: user.email,            // optional
  plan: user.plan,              // recommended, helps the agent
  createdAt: user.createdAt,    // optional: signup date, Unix time in seconds
})

userId and displayName are always required. In a B2B app, tenantId and tenantName are required too; in a B2C app, leave them out. role and plan are recommended because the agent reads both, and without them it sees “unknown”. The rest are optional: fill what your app has, and delete the others.

Apps with both

If some of your users belong to a company or workspace and others sign up on their own, pass the tenant when the user has one and leave it out when they don’t:

HelpAlive.identify({
  userId: String(user.id),
  displayName: user.name,
  tenantId: user.company ? String(user.company.id) : undefined,
  tenantName: user.company ? user.company.name : undefined,
});

B2C customers refers to the group in your dashboard where users sent without a tenant appear together.

Field	Required	What it is
`userId`	Yes	Your own id for this user, as text, up to 255 characters. It must not change, so don’t use an email address if users can change theirs.
`tenantId`	B2B	Their company or workspace id, as text, up to 255 characters. Leave it out for users with no tenant: your dashboard groups them as B2C customers.
`tenantName`	B2B	The company’s name, shown in your dashboard. Without it, the dashboard calls the tenant “Tenant” and a short form of its id.
`displayName`	Yes	The person’s name, for example `"Priya Sharma"`, or their email. Shown in your dashboard.
`email`	No	Their email address, shown and searchable in your dashboard.
`role`	Recommended	Their role in your app, for example `"admin"`, `"editor"` or `"viewer"`.
`plan`	Recommended	Their plan in your app, for example `"free"` or `"pro"`.
`createdAt`	No	When they signed up, as Unix time in seconds, for example `1704067200` for 1 January 2024. Milliseconds and date strings are ignored. Without it, HelpAlive uses the day it first saw the person.
`userToken`	No	The token your server makes once you verify users. With a token, `userId` and `tenantId` come from the token.
`refreshUserToken`	No	With `userToken`: a function that returns a fresh token from your server. If a token has expired, HelpAlive calls it and sends the request again, so the user notices nothing. A fresh token must name the same user and tenant.

A tenant refers to one of your customers: the company, workspace or account a user belongs to in your app. Key concepts defines it with the other terms.

Types matter

userId and tenantId can be text or a number. 42 and "42" are the same person.
Pass displayName, email, role and plan as text. A number in displayName, role or plan is turned into text. A field of another type, or one too long, is left out, and the call goes on without it. Keep role and plan short, as a name rather than a description.
An empty userId, or a userId or tenantId over 255 characters, stops the call, and the agent doesn’t load on that page.

These problems show nothing on screen. Add data-debug to the tag to see them in the browser console.

What the agent uses

The agent reads the user’s display name, role, plan and sign-up date, so it can fit its answers to them. It never receives the email field, but it does see an email you pass as displayName. The fields also label the user in your dashboard, for example in Audience.

Logging out

Call reset() in your logout code, apart from your identify() call. Also call it wherever your app ends a session, for example where a request comes back signed out:

// In your logout code, and wherever your app ends a session. Until this runs,
// the browser keeps the person, and the next visitor's events count as theirs.
HelpAlive.reset()

reset() forgets the user, their tenant and their token. It closes the agent and clears its conversation from the browser. The next person on the same browser never sees the last one’s chat. Never put reset() straight after identify(), because it would forget the user at once and the agent would never appear. If your logout navigates away before reset() can run, HelpAlive still notices when a different user is identified on that browser. It closes the previous user’s agent before loading the new one.

Switching company without reloading

If users can switch company or workspace without a page reload, call identify() again with the new tenantId after the switch. HelpAlive counts what they do from then on under the new tenant, and reloads the agent for it. Once you verify users, the tenant comes from the user token. Get a new token for the new company from your server, and pass that to identify().

Before identify() runs

No events are sent for a visitor until identify() runs. Events wait in the page and are dropped if the visitor leaves without signing in. The agent doesn’t appear for them. The one request before sign-in is a small start-up check: our script’s version and the page’s host and path.

Check it works

Sign in to your app and click around, then come back to Settings → Setup & API Key. Step Add HelpAlive to your app gets a check and says when it last saw a signed-in user, for example “Recognized a signed-in person 3 minutes ago.” The user also appears in Audience, under their tenant or under B2C customers. Step 1 stays there because our script is on your pages, but identify() isn’t running, or it was refused. Step Add HelpAlive to your app says “On your pages. Waiting for someone to sign in to your app.” Check that the queue lines come first, that the call runs on every page load after login, and that userId is text.

Why do users show under the wrong company?

Users show under the wrong company when your app switched company without calling identify() again. Call it after every switch.

Why does the next person on a shared computer see the last one’s chat?

The next person sees the last one’s chat because reset() doesn’t run at logout. Add it to your logout code and wherever your app ends a session.

Verify users

Optional, and recommended before you open the agent to all your users.

Consent

Wait for your cookie banner before loading HelpAlive.

JavaScript reference

Every call and attribute.

Install

Install by framework

Install options and security

Reference

Identify users and tenants with HelpAlive.identify()

identify() at a glance

Prerequisites

When to call identify()

The call

Apps with both

Types matter

What the agent uses

Logging out

Switching company without reloading

Before identify() runs

Check it works

Why do users show under the wrong company?

Why does the next person on a shared computer see the last one’s chat?

Next

Verify users

Consent

JavaScript reference

​identify() at a glance

​Prerequisites

​When to call identify()

​The call

​Apps with both

​Types matter

​What the agent uses

​Logging out

​Switching company without reloading

​Before identify() runs

​Check it works

​Why does step 1 stay on Waiting for someone to sign in?

​Why do users show under the wrong company?

​Why does the next person on a shared computer see the last one’s chat?

​Next

Verify users

Consent

JavaScript reference

identify() at a glance

Prerequisites

When to call identify()

The call

Apps with both

Types matter

What the agent uses

Logging out

Switching company without reloading

Before identify() runs

Check it works

Why does step 1 stay on Waiting for someone to sign in?

Why do users show under the wrong company?

Why does the next person on a shared computer see the last one’s chat?

Next