User Identification & Management

Track and manage users on Web Chat.

How to identify and manage users

Before you proceed

This section describes how you can integrate users with the legacy method. For integrating with the new Identity System, please refer to: User Hub.

We recommend using the new Identity System if you require faster context collection, an easier agent experience, and enhanced security and spam protection.

Logged in users

Overview

A logged-in user uses Web Chat after providing your website with a username and password. If your website has logged-in users, we highly recommend passing user identifiers (userId and/or userEmail) with the helpshiftConfig object at the time of initialization. This helps your Agents provide a personalized support experience to your users, no matter which device or browser your end users are using. Passing the user identifiers to Web Chat also ensures ensures that a user's conversations are available only to them when they log in.

What to provide as user identifiers

You can set the userId and/or userEmail to identify your users. We highly recommend using a userId to identify your users. If you use emails to identify your users, you must pass them with the userEmail field with the helpshiftConfig object.

The following rules apply when you use both, userId and userEmail.

• When looking the user up in the Helpshift system, the priority of userId is higher than that of userEmail.
• When the userId matches that of an existing user, the existing user's email gets updated, if the email is provided.
• When the userEmail matches that of an existing user, the following rules apply:
  • If the userId doesn't exist for the user matched by the email, then the userId would be added to that user, if a userId is provided.
  • If the userId already exists for the user matched by the email, then a new user would be created, if a different userId is provided.

How to provide user's information

The helpshiftConfig object accepts the following parameters:

Parameter	Description	Important considerations
userName	A user's name. Provide the name you'd like the Agents to use to address the user. If you don't have the user's name in your systems, you may leave it blank. The Identity Bot, if enabled, will ask the user for their name. If you provide a value for the name, then the Identity Bot will not ask the user for their name again.	Max length – 255 characters. Values longer than this will be truncated.
userId	A user's unique identifier. The userId values must be unique for your users, i.e. you should not use the same userId for different users.	1. The max length is 750 characters. Values longer than this will result in the creation of an anonymous user. 2. Leading/trailing spaces are not allowed. Spaces within the userId value are allowed, though. userId values with leading/trailing spaces will result in the creation of an anonymous user. 3. The userId value is case-sensitive, e.g. "1abc" is different than "1ABC". 4. Do not provide an email address as the userId. If you use email addresses to identify users, provide them with userEmail. 5. If you are using userId as well as userEmail, ensure that userId is present in all subsequent pages. Providing just the email may return another user's conversations, if multiple profiles have the same email.
userEmail	A user's email address. If you don't know the user's email, you may leave it blank. The Identity Bot, if enabled, will ask the user for their email. If you provide a value for the email, then the Identity Bot will not ask the user for their email again.	1. The email should be in a valid format, e.g. "foobar@example.com". Invalid emails will result in the creation of an anonymous user. 2. Leading/trailing spaces are not allowed. Emails with leading/trailing spaces will result in the creation of an anonymous user. 3. The email value is case insensitive, e.g. "foobar@example.com" is same as "FOObar@Example.Com".
userAuthToken	A user authentication token is generated via Hash Based Message Authentication Code (HMAC) using SHA256. You should provide a userAuthToken if you want to ensure that 3rd parties cannot file issues on behalf of your users or update their properties. You can find more details under the Verifying the identity of users section.	A valid userAuthToken should be provided in order to ensure your users can file issues. Learn more here

Note

• In order to create a logged-in user in Helpshift, the use of either userId or userEmail is required.
• All the parameter values should be of type string. Integer and decimal values are invalid.

Example Embed Code

var PLATFORM_ID = "foo",
  DOMAIN = "bar";

window.helpshiftConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  userId: "captain_planet",
  userEmail: "captain@example.com",
  userName: "Captain Planet",
  userAuthToken: "ab+dKOFgxspi3ARXSa/zSdN4wFrU6CQu3hJzHQtXYRI",
};

Logging the users out

Once a user logs out from your website, you should stop sending the user identifiers with the helpshiftConfig object to ensure that other users can't view this user's conversations. After you log a user out, only the conversations started by anonymous users using that specific browser will be visible.

Anonymous Users

Overview

An anonymous user is one who accesses Web Chat without providing your website with a username and password. If a user identifier is not passed with the helpshiftConfig object at the time on initialization, Helpshift assumes that the end user is an anonymous user, i.e. is not currently logged in. Similarly, if a user identifier is passed with the helpshiftConfig object, then the end user is assumed to be a logged-in user.

If your use-case involves multiple logged-in or anonymous users using the same device, ideally you wouldn't want the conversations to be shared across logins. In this case, you should use the clearAnonymousUserOnLogin option with the helpshiftConfig object at the time of initialization. If you set clearAnonymousUserOnLogin to true, then anonymous users will be cleared from Web Chat whenever a new user logs in. Once cleared, such users, and their conversations, are not fetched again.

Note

The anonymous user will be cleared from Web Chat after 7 days to make sure that the conversations by anonymous users do not persist on the browsers forever.

Example Embed Code

var PLATFORM_ID = "foo",
  DOMAIN = "bar";

window.helpshiftConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  userId: "piano_man",
  clearAnonymousUserOnLogin: true,
};

Note

The clearAnonymousUserOnLogin functionality does not impact the logged-in user's experience at all.

Verifying the identity of users

Configuring Identity Verification in your app

Overview

User Identity Verification is a security measure that verifies that all requests made from your Web Chat widget to Helpshift are coming from authentic end users. This prevents 3rd parties or hackers from impersonating your users. You can learn more about User Identity Verification and the steps to configure it here.

In order to ensure your users are verified, you should provide a "user authentication token" with the helpshiftConfig object at the time of initialization. You can find the steps to generate a "user authentication token" here. The "user authentication token" is an HMAC Digest, which is generated via HMAC using SHA256.

Sending the user authentication token to verify users' identity

You can send the "user authentication token" along with the userAuthToken key of the helpshiftConfig object. If Identity Verification is enabled on the Helpshift Dashboard, Helpshift recalculates the unique user authentication token using the shared secret key, and compares the user authentication token sent by you to the recalculated value. If they're equal, the user's identity is verified, and the user is able to file Issues.

Note

• If the secret key is regenerated for an app on the Admin Dashboard, you should ensure you update your endpoint code as well in order to generate a valid "user authentication token". Following which, your Admins should delete the old secret key from the Dashboard in order to ensure requests using a "user authentication token" generated using the old secret key become invalid.
• If fullPrivacy is true, then the "user authentication token" should be generated only using the userId.

Example Embed Code

var PLATFORM_ID = "foo",
  DOMAIN = "bar";

window.helpshiftConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  userId: "captain_planet",
  userEmail: "captain@example.com",
  userName: "Captain Planet",
  userAuthToken: "ab+dKOFgxspi3ARXSa/zSdN4wFrU6CQu3hJzHQtXYRI",
};

Identity Verification failure

Overview

When making a request to Helpshift with no userAuthToken or an invalid userAuthToken, Identity Verification will fail. If Identity Verification fails, the following will hold true.

• Anonymous users (users for whom you do not provide any identifiers) are always able to file issues.
• Logged-in users (users for whom you provide an identifier such as userId or userEmail) are not able to file issues or see conversations if they are unverified. Unverified logged-in users will have the following experience:
  • The Web Chat launcher icon will not be shown when the web page is loaded.
  • The Web Chat widget will show an error (if it's opened by means of the open API).
• If the logged-in users are verified (i.e. a valid userAuthToken is provided), they are able to see their previous conversations and create new Issues. The UI for verified logged-in users looks and works exactly the same as it would if Identity Verification were turned off. Only unverified users are impacted as described above.

User auth failure event

If you wish to programmatically handle Identity Verification failure, you can do so using the userAuthFailure event:

interface AuthFailureData {
  message: "missing user auth token" | "invalid user auth token"
}

const userAuthFailureHandler = function ({ message }: AuthFailureData) {
  console.log(message)
  // ... Handle auth failure
};

Helpshift(
  "addEventListener",
  "userAuthFailure",
  userAuthFailureHandler
);

To stop listening to this event, you can remove the event listener:

Helpshift("removeEventListener", "userAuthFailure", userAuthFailureHandler)

Testing & Troubleshooting

How do I test that I have User Identity Verification set up correctly?