Enable user authentication mode via JS API

Know everything about your registered customers.
Written by Artem
Updated 1 month ago

User authentication mode provides a seamless experience for a business and for a customer across different devices. It offers continuity across web, iOS and Android platforms and lets you keep all interactions with a given customer in the same chat thread no matter what device he/she is logged in from. User authentication mode helps make sure that one user can’t impersonate another and therefore we strongly recommend all our clients to enable this mode.


Common usage

The most common usage of the User authentication mode is to integrate it with your registration/login system. You can install HelpCrunch chat widget on your landing page to talk to your visitors, for example, and inside your service (in-app messenger) to support your registered users. Once your visitor registers/logs in with your service and gets a User ID in your database, you can enable the User authentication mode for that user.


How it works

In order to enable User authentication mode, you should modify HelpCrunch Initialization code. We initiate the user authentication mode once you specify a user_id parameter inside user object during the initialization process. Example:

HelpCrunch('init', window.helpcrunchSettings.organization, {
  appId: <your_appId>,
  user: {
    email: '<user email>',
    name: '<user name>',
    phone: '<phone number>',
    company: '<company name>',
    user_id: '<user_id>',


Please note that the user_id attribute must be unique for each user!

Make sure you're passing it as a string

When you send us the user_id, e.g. 12345, we automatically authenticate this user and load all previous corresponding chat history and user personal/behavioral data (aka user profile) to your agent chat and chat history to user’s chat. So, if a user logs in to your service/product/app from his home desktop first, talks to you via chat, then logs in from his work laptop – the chat history and all the related user data will be always available for you and your customer.

Important note!

It is highly recommended to specify a unique user_id together with user name and user email address.

Otherwise, the email address field in a user profile will be empty, and the user name field will contain randomly generated names like Giant Duck (anonym) or Colored Leopard (anonym).

If the user authentication mode is enabled, a pre-chat form will not be displayed.

If you send us just a user name and/or user email without indicating a user_id —the user authentication mode will not be enabled and a pre-chat form will be displayed with prefilled name and/or email fields.

Authenticated users

These are all users available in HelpCrunch Users section. If you enable User authentication mode, all registered/logged in users will automatically fall into Contacts section even if they’ve had no chats with you previously. You can also import users from a CSV file thus making them authenticated. Plus any user, who had a chat with you (at least one successfully sent message from the user who filled in his data in the pre-chat form) is considered an authenticated user.


If you want to be sure that no one substitutes the user ID to view another person’s chat history and chat under there name, you have two options:

1. Fast and easy way: Hash your user ID's with hash salt and put this hash to user_id field instead of a real ID (it’s okay to pass the string to this field)

2. More complicated way: Send the security_hash parameter right with the user_id. It is optional and can be any string (like password hash, for example). After you have sent the security_hash once – you will need to send it every time for current user_id or you’ll get 403 and a clean chat. 

Next step is to forward your custom data attributes about your customers. Read more

Did this answer your question?