Skip to main content

Users

Track and manage users on Helpshift Widget.

How to identify and manage users​

Logged in users​

Overview​

A logged-in user uses Helpshift Widget 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 helpshiftWidgetConfig 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 Helpshift Widget also 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 helpshiftWidgetConfig 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 helpshiftWidgetConfig object accepts the following parameters:

ParameterDescriptionImportant considerations
userNameA 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.
userIdA 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.
userEmailA 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".
userAuthTokenA 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 = "<YOUR_PLATFORM_ID>",
  DOMAIN = "<YOUR_DOMAIN>",
  APP_ID = "<YOUR_APP_ID>",
  WIDGET_TYPE = "<WIDGET_TYPE>";

window.helpshiftWidgetConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  appId: APP_ID,
  widgetType: WIDGET_TYPE,
  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 helpshiftWidgetConfig 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 Helpshift Widget without providing your website with a username and password. If a user identifier is not passed with the helpshiftWidgetConfig 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 helpshiftWidgetConfig 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 helpshiftWidgetConfig 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.

Example Embed Code​
var PLATFORM_ID = "<YOUR_PLATFORM_ID>",
  DOMAIN = "<YOUR_DOMAIN>",
  APP_ID = "<YOUR_APP_ID>",
  WIDGET_TYPE = "<WIDGET_TYPE>";

window.helpshiftWidgetConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  appId: APP_ID,
  widgetType: WIDGET_TYPE,
  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 Helpshift 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 helpshiftWidgetConfig 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 helpshiftWidgetConfig 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 = "<YOUR_PLATFORM_ID>",
  DOMAIN = "<YOUR_DOMAIN>",
  APP_ID = "<YOUR_APP_ID>",
  WIDGET_TYPE = "<WIDGET_TYPE>";

window.helpshiftWidgetConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  appId: APP_ID,
  widgetType: WIDGET_TYPE,
  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 Chat is open in Helpshift Widget.
    • Smart form submissions will fail in Helpcenter inside Helpshift Widget.
  • 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.

Testing & Troubleshooting​

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