How to install HelpCrunch on your app (for logged-in users)

If you want to integrate HelpCrunch with your app and provide a seamless experience for your logged-in users, this guide is for you.
Written by Ana
Updated 10 months ago

Authenticated users

Authenticated users are all users available in HelpCrunch 'Contacts' section.

1. If you enable the User Authentication mode, all registered/logged-in users will automatically fall into the 'Contacts' section even if they had no chats conversations with you.

2. Users who had chat conversations with you are considered authenticated if they've filled in a pre-chat form and sent you at least one message.

3. You can also import contacts from a CSV file and make them authenticated as well.

What is the User Authentication mode?

User authentication mode provides a seamless experience for businesss and customers across different devices and web, iOS and Android platforms.

What it does is lets you keep all interactions with each customer in the same chat thread, no matter what device they've logged in from. It also makes sure that one user can’t impersonate another, which is why we strongly recommend to enable the User Authentification mode.

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 or website to talk to your visitors and then integrate it with your service and use as an in-app messenger to support your registered users.

Once your visitor registers/logs in to your service and gets their personal User ID in your database, you can enable the User authentication mode for that user.

How to enable the User Authentification mode

In order to enable the User Authentication mode, you should modify HelpCrunch Initialization code a little bit.

We initiate the User Authentication mode once you specify a user_id parameter inside user object during the initialization process.


HelpCrunch('init', '<your organization domain>', {
  applicationId: <application id>,
  applicationSecret: '<application secret>',
  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

Usually, our clients use User ID's from their user database).

When you send us the user_id (e.g. 12345), we automatically authenticate a corresponding user. This way, we're able to load their previous chat history and user 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 their home desktop first, talks to you via chat, then logs in from their work laptop – their 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.


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?