Hello 👋 How can we help?

JS API methods

showChatWidget, updateUser, setPhraseList and more usefull stuff
Written by Artem
Updated 4 days ago

HelpCrunch widget provides you with small JavaScript API on your website. With it you can control and customize your chat and widget behavior.

showChatWidget

Shows the chat widget (chat start button) after the initialization or after it was hidden by hideChatWidget.

No parameters or returns.

HelpCrunch('showChatWidget');

hideChatWidget

Hides the chat widget (chat start button) after it was displayed by showChatWidget.

No parameters or returns.

HelpCrunch('hideChatWidget');

openChat

Opens the HelpCrunch chat. Can be called without displaying the widget.

No parameters or returns.

HelpCrunch('openChat');

closeChat

Closes the HelpCrunch chat after it was opened by openChat.

No parameters or returns.

HelpCrunch('closeChat');

init 

Initializes the HelpCrunch widget on your website page. All web SDK methods that were called before this method will run after it finishes the initialization.

You can take this method with all required parameters right from your HelpCrunch account at Settings page → Set up & Customize → Website Widgets → Your app name → Setup

Parameters:

  • organization domain: string, domain of your organization, that you have entered during the registration, you can check it in url of your admin account, like DOMAIN.helpcrunch.com.
  • options: object
  • applicationId: string
  • applicationSecret: string
  • user (optional): object – if the user is authenticated at your website, you can send the user’s data right during the initialization to authenticate the user in HelpCrunch chat automatically and make fewer server requests later. Read more about it in user authentication mode section, view detailed user format in web SDK user section
  • signature (optional): string – needed only in user authentication mode when you want to protect your user data with backend security signature. Read more about it in security signature section.

Default initialization:

HelpCrunch('init', '<your organization domain / string>', {
  applicationId: ,
  applicationSecret: '<application secret / string>',
});

Initialization with all user/lead data:

HelpCrunch('init', '<your organization domain / string>', {
  applicationId: ,
  applicationSecret: '<application secret / string>',
  user: {
    email: '<user email / email>',
    name: '<user name / string>',
    phone: '<phone number / string>',
    user_id: '<user_id /string>',
    security_hash: '<security_hash /string>',
      custom_data: {
      money_spent: 2500,
      subscription: 'gold',
      accepted_agreement: true,
    },
  },
  signature: 'e8aa8af95cd6a05b80308dcb3dd6901d',
});

updateUser

Use it to add or update current customer parameters, such as name, email, phone, company and customData (an object with any random data you want to write). If there is no user initialized for the current visitor, this method will create a new user and you will be able to see it at the Contacts page in your HelpCrunch account. This method is useful when the user makes any changes in his main attributes you want to write and you want to see it in your HelpCrunch account instantly. Parameters:

  • user: object – view detailed user format in web SDK user section
  • signature (optional): string – needed only in user authentication mode when you want protect your user data with backend security signature. Read more about it in security signature section
  • callback (optional): function
var user = {
  email: '<user email / email>',
  name: '<user name / string>',
  user_id: '<user id / string>',
  phone: '<phone number / string>',
  security_hash: '<security_hash /string>',
  custom_data: {
    money_spent: 2500,
    subscription: 'gold',
    accepted_agreement: true,
  },
};
HelpCrunch('updateUser', user, 'e8aa8af95cd6a05b80308dcb3dd6901d', function() {});

Example:

In your single page application user changes (or adds) his email. To see this change in HelpCrunch admin panel, you can just call

var userEmail = 'email@somedomain.com';
HelpCrunch('updateUser', { email: userEmail });

userAuth

With the help of userAuth method, you can authorize a customer. This method requires two parameters – ‘email’ and ‘user_id’. However, you can add other parameters as well – such as ‘name’, ‘company’, or ‘phone’.
Usually, this method comes in useful if you want to postpone authorization until after some triggers have been activated or if your website has a single page with dynamically updated content (Single-Page Application).

  • user: object – view detailed user format in web SDK user section.
  • signature (optional): string – needed only in user authentication mode when you want protect your user data with backend security signature. Read more about it in security signature section
  • callback (optional): function
HelpCrunch('userAuth', {
  email: '<user email / email>',
  user_id: '<user id / string>'
});

updateUserData

Updates current user’s custom data. Custom data is an object with any random data you want to write and then use in your HelpCrunch account. Read more about it in web SDK custom data section. This method is useful when the user makes any changes in his custom attributes and you want to see it in your HelpCrunch account instantly. Parameters:

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

Example:

You want to count how many times your user clicked some important button: you store counter in localStorage and onClick call

document.getElementById('important-button').onclick = function () {
  var counter = window.localStorage.getItem('counter');
  counter++;
  window.localStorage.setItem('counter', counter);
  HelpCrunch('updateUserData', { importantButtonClicks: counter });
}

trackEvent

You can track any custom events the user does in your website and view his event history in HelpCrunch account. Read more about it in the track custom events section.

Parameters:

  • eventName: string
HelpCrunch('trackEvent', eventName);

Example:

You want to know that user has clicked the “checkout” button. The code will look like this:

document.getElementById('checkout-button').onclick = function() {
  HelpCrunch('trackEvent', 'checkoutButtonClick');
}

setPhraseList

Call setPhraseList if you want to launch a custom localization or custom chat texts. By default there are 6 languages available and the chat will pick the localization corresponding to the browser language. If that language is not found, chat will display the default one. Read more about it in the localization section.

Parameters:

  • phraseListName: string
HelpCrunch('setPhraseList', phraseListName);

Example:

You have created a Klingon language phrase-list in you admin account and called it “klingonian”. To enable it in the HelpCrunch chat on your page, run this code before showing the chat widget:

HelpCrunch('setPhraseList', 'klingonian');

sendProactiveChatAutoMessage

HelpCrunch has a proactive chat auto-message system to automatically address visitors and leads. You can configure the auto-message rules in your HelpCrunch account or just call it from web SDK JS API. Read more about it in the send proactive chat auto-messages with JavaScript API section.

Parameters:

  • autoMessageId: number
HelpCrunch('sendProactiveChatAutoMessage', autoMessageId);

Example:

You want to offer a discount to your customer if he sorts your goods by price in ascending order or just clicks “Get a discount!” button (or whatever you want). For this, you need to create a proactive chat auto-message in your HelpCrunch account, enable it and get its ID from its editing page. Assuming that ID is (for example) 1420, the code can be:

var proposeDiscount = function () {
  HelpCrunch('sendProactiveChatAutoMessage', 1420);
}
document.getElementById('i-want-discount-button').onclick = proposeDiscount;
document.getElementsByClassName('sort-goods').onclick = function (event) {
  if (event.target.attributes.order == 'asc' && event.target.attributes.field == 'price') {
    proposeDiscount();
  }
}

sendUserMessage

Sometimes you need to send your support agent a message on behalf of your website user on some custom user action. This method is right for it.

Parameters:

  • messageText: string
HelpCrunch('sendUserMessage', messageText);

Example:

You want your support agent to receive a message with “CALLBACK: +12312312313” text when the user enters his phone number on some form and clicks a “Call me back” button on your website. This code will look like:

document.getElementById('callback-button').onclick = function () {
  var phoneNumber = document.getElementById('callback-input').value;
  if (phoneNumber) {
    HelpCrunch('sendUserMessage', 'CALLBACK: ' + phoneNumber);
  }
}

typeUserMessage

This method allows adding a prefilled message to a text area without sending it.

Parameters:

  • messageText: string
HelpCrunch('typeUserMessage', messageText);

logout

On some websites user can have multiple accounts and can login/logout to switch between them. If you use user authentication mode you can do the same for your HelpCrunch widget, so the data from one user account will not pass to another. You can use logout method to do it:

No parameters or returns.

HelpCrunch('logout');

Did this answer your question?