Installing HelpCrunch Live Chat 2.0 on your web enables you to communicate with your web app visitors and registered users. If you are looking to get going, follow these step-by-step instructions.

1. Integration

Create a new web app

To add a new app, go to your HelpCrunch account, open Settings and find Add application there.

Install the HelpCrunch JS code into your web app to track live user data.

Choose “View API” in the list of applications to generate and copy js code. Paste js code to every page of your website where you want HelpCrunch live chat to appear.

2. API reference

HelpCrunch initialization

HelpCrunch('init', '<your organization domain>', {
applicationId: <application id>,
applicationSecret: '<application secret>'

To display HelpCrunch Live Chat widget use

And set chat position using:
HelpCrunch('showChatWidget', options);

Where options is javascript object with the following properties:
position (string). You have two options where to place chat widget (either left or right).
open (boolean). The chat is closed by default. To start writing a message, users has to click on the widget. However, it is possible to have the chat open using this property.

To hide HelpCrunch Live Chat widget use


To display text from phrase list use

HelpCrunch('setPhraseList', '<phrase list name>');

Read more about HelpCrunch messenger customization and localization here.

To manually open and close HelpCrunch Live Chat use


Include standard user attributes

To receive access to customer personal data enable standard data collection during HelpCrunch initialization.

var user = {
email: '<user email>',
name: '<user name>',
user_id: '<user id>'
HelpCrunch('init', '<your organization domain>', {
applicationId: <application id>,
applicationSecret: '<application secret>',
user: user

Or invoke ‘updateUser’ on SDK
HelpCrunch('updateUser', user);

Add custom attributes to meet specific business criteria

HelpCrunch lets you send custom attributes about your customers to collect user data that are relevant to your business.

var userData = {money_spent: 2500, subscription: 'gold'};
HelpCrunch('updateUserData', userData);

List of SDK events

SDK state

HelpCrunch('onReady', function() {
// Will be called once when SDK is ready and browser registered

Chat state

HelpCrunch('onChatOpen', function() {});
HelpCrunch('onChatClose', function() {});

User messages

HelpCrunch('onNewUnreadMessages', function(event) {
// Executed every time when number of unread messages is changed

3. User authentication mode

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 to keep customer interaction in one and the same chat thread no matter what device the customer 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.

How it works

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

HelpCrunch('init', '<your organization domain>', {
applicationId: <application id>,
applicationSecret: '<application secret>',
user: {
email: '<user email>',
name: '<user name>',
user_id: '<user_id>'

Important note: user_id attribute must be unique (usually our clients use a User ID from their user database).

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 send user name and user email together with the user_id. Otherwise the email address field in the user profile will be empty, and user name will be randomly generated by us, e.g. Giant Duck (anonym) or Colored Leopard (anonym).

Important note: if the user authentication mode is enabled, the pre-chat form will not be displayed before the chat start. If you send us just the user name and/or user email without indicating the user_id – the user authentication mode will not be enabled, but the name and/or email fields of the pre-chat form will be pre-filled and the form will be displayed before the chat start.

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.

Authenticated users

These are all users available in HelpCrunch Users section. If you enable User authentication mode, all registered/loggedin users will automatically fall into Users 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) is considered an authenticated user.

4. Track custom events

You can send HelpCrunch any customer activities performed by users in your web or mobile app.

Once you’re sending HelpCrunch this data, events will be tracked and shown in customer profile in order as it happens.

For example, you could track how users navigate in your web or mobile app, what pages users visit, what goods users have added to their shopping cart, what goods users have purchased in your app, etc.

You can submit an event using the trackEvent method. This will associate the event with the currently logged in user and send it to HelpCrunch.

HelpCrunch('trackEvent', eventName, params);

The last argument is javascript object and can contain additional event data (url, title, etc.)

By default HelpCrunch widget tracks user navigation by “Page View” events.

5. Create custom chat widget

There is a chat widget available by default. However, you can create your own widget that fits better with your design.

Copy API code in accordance with step 1.

Exclude standard widget initialization code from copied API code


Once SDK is installed, use onReady event to show your custom widget

HelpCrunch('onReady', function() {
// Show your widget

To open the chat use


If you need to change your widget view depending on your chat is open or closed, use the following events

HelpCrunch('onChatOpen', function() {});
HelpCrunch('onChatClose', function() {});

To display a number of unread messages use

HelpCrunch('onNewUnreadMessages', function(event) {
// event.unreadMessages

6. Integrate Google Analytics tracking

If you want to track HelpCrunch chat/widget events in your Google Analytics account, you can easily add tracking codes to your web page with HelpCrunch widget. For example, if your Google Analytics function is “ga” (default one) you will need to add these codes after HelpCrunch(‘init’):

Track when your customer sends a message in chat:

HelpCrunch('onCustomerMessage', function (event) {
ga('send', 'event', 'customer', 'sendChatMessage’);

Track when your customer opens the chat:

HelpCrunch('onChatOpen', function () {
ga('send', 'event', 'customer', 'opensChat’);

Track when your customer closes the chat:

HelpCrunch('onChatClose', function () {
ga('send', 'event', 'customer', 'opensChat’);

Track when your customer receives a new message:

HelpCrunch('onNewUnreadMessages', function () {
ga('send', 'event', 'customer', 'getsNewMessage’);

If you want to track any other event in Google Analytics – please contact us in chat from your HelpCrunch admin account and we will arrange it for you.

7. Localization

The following steps describe the localization process by using phrase lists.

Step 1. Adding localizations and phrase lists

First of all you need to create your Phrase Lists. Go to your HelpCrunch account, then open Settings / Website Widgets, find your Website Widget, click on it and open Localization tab there. Add a separate Phrase List for each language that you want to support. Then edit each phrase list texts to match the language.

Important note: If you want to enable automatic detection of localization depending on user’s browser language, you should use the two-letter language code as the Phrase List Name.
Examples: en, fr, de, pt, es. (see full list of ISO 639-1 codes)

Step 2. Enabling localizations

In order to enable any exact Phrase List by its name you should add the following command to the chat widget js code:

HelpCrunch('setPhraseList', 'en');

If you named all your Phrase Lists with the two-letter language codes, you can add the following command to the chat widget js code in order to automatically detect the user’s browser language and enable the corresponding Phrase List:

HelpCrunch('setPhraseList', navigator.language.slice(0,2));

8. Send proactive chat auto-messages with JavaScript API

Sometimes you need to send a proactive chat auto-message after a user does some custom action on your website or when proactive chat rules are just not enough to meet some complex conditions. In these cases, you can trigger a proactive chat auto-message with JavaScript.

All you need to know is your proactive chat auto-message ID. You can view it after you have created the auto-message at the header of its edit page (like “Edit Auto Message #1420”).

For example, if auto-message ID is 1420, you can fire it by code:

HelpCrunch('sendProactiveChatAutoMessage', 1420);

If you want to create a proactive chat auto-message that will be triggered only by JavaScript API call, you should choose radio button “Launch only with widget API” in “Proactive chat rules” section on the auto-message create/edit page.