Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.helpalive.com/llms.txt

Use this file to discover all available pages before exploring further.

identify() is the only call you have to make beyond the script tag. It tells HelpAlive which user is using your product, which workspace they belong to, and what traits to use for segmentation and personalization.

​
When to call it

Call identify() once per session, right after the user logs in. Common places to put it:
  • Your login callback.
  • The first authenticated page or layout that loads after sign-in.
  • Anywhere the user object becomes available on the client.
If identify() runs before the script has finished loading, the call is queued and replayed automatically — you don’t need to add any extra checks.

​
Signature

HelpAlive.identify({
  userId:      string;   // required — your stable app user ID
  tenantId:    string;   // required — workspace/org ID, or "default"
  tenantName?: string;
  displayName?:string;
  email?:      string;
  role?:       string;
  plan?:       string;
  createdAt?:  string;   // when the user signed up
});

​
Field reference

FieldRequiredDescription
userIdYesYour app’s stable user ID. Must not change across sessions. Avoid using email if it can change.
tenantIdYesWorkspace or organization ID. If your app doesn’t have multi-tenancy, pass "default".
tenantNameNoDisplay name for the workspace. Shown in Insight → Audience in your dashboard instead of the raw ID.
displayNameNoFull name of the user (e.g. "Priya Sharma"). Recommend firstName + " " + lastName.
emailNoUser’s email. Used for display and search. Keep userId as the stable identifier.
roleNoUser’s role or permission level (e.g. "admin", "editor", "viewer"). Helps segment behavior.
planNoSubscription tier (e.g. "free", "pro", "enterprise"). Enables plan-segmented insights and chatbot behavior.
createdAtNoWhen the user signed up. Helps the AI assistant tailor its tone for new vs. seasoned users.

​
Why identify() matters

Until you call identify(), HelpAlive doesn’t record any activity for that user. Once you call it, HelpAlive can:
  • Connect activity to real users across sessions and devices.
  • Group users by workspace so your dashboard reflects the way you actually think about customers.
  • Personalize the AI assistant’s greetings and suggestions based on the user’s plan, role, and recent activity.
  • Show per-user profiles in your dashboard so you can see what any individual customer has been doing.

​
Example

HelpAlive.identify({
  userId:      "user_8x92k",
  tenantId:    "acme-corp",
  tenantName:  "Acme Corp",
  displayName: "Priya Sharma",
  email:       "priya@acme.com",
  role:        "admin",
  plan:        "pro",
  createdAt:   "2024-11-03T09:00:00Z"
});

​
Apps without workspaces

If your product has one user per account and no concept of workspaces, pass a fixed value for tenantId: 
HelpAlive.identify({
  userId:   "user_8x92k",
  tenantId: "default"
});
You can switch to real workspace IDs later. Existing activity and profiles will be re-grouped automatically.

​
Workspace switching mid-session

If a user switches workspaces without reloading the page (common in B2B apps with a workspace switcher), call identify() again with the new tenantId. HelpAlive will start recording their activity under the new workspace from that point on. 
// User clicks "Switch to Beta Inc."
HelpAlive.identify({
  userId:   "user_8x92k",
  tenantId: "beta-inc",
  tenantName: "Beta Inc."
});

​
Logout

When the user logs out, the SDK clears identity automatically when the session ends. If your app doesn’t fully reload between users (a shared device, for example), you can clear it manually with HelpAlive.reset() to prevent the next user inheriting the previous identity. For most apps, this isn’t needed.

​
Anonymous sessions

If you never call identify(), HelpAlive doesn’t record any activity for that user. Anonymous browsing isn’t stored — by design. This keeps your analytics clean and keeps unauthenticated traffic out of the AI assistant.

​
Things to know

Use your database ID, a UUID, or any other ID that doesn’t change. Don’t use email — if a user changes their email later, their activity will end up under two separate profiles.
email makes the user searchable in your dashboard, but HelpAlive uses userId to recognize them. Always send a stable userId.
Pass "default" if your app has no concept of workspaces. HelpAlive groups activity by workspace, so a value is required even if you only have one.
Safe and expected. Each call updates the user’s identity. Identical calls don’t create duplicates.
These two fields are stored on the user profile so your team can search and support. They never appear in raw activity records, and the user can be deleted on request.

​
Next steps

Configure consent

Pause tracking until your cookie banner returns a decision.

Set up the Agent

Train the AI assistant on your docs.