JS API methods

showChatWidget, updateUser, setLocalization and more usefull stuff

Written by Konstantine

Updated 1 month ago

HelpCrunch widget provides you with a 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
- appId: 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>', {
  appId: '<application id / string>',
});

Initialization with all user/lead data:

HelpCrunch('init', '<your organization domain / string>', {
  appId:  '<application id / string>',
  user: {
    email: '<user email / email>',
    name: '<user name / string>',
    phone: '<phone number / string>',
    company: '<company name / string>',
    user_id: '<user id /string>',
    security_hash: '<security hash / string>',
    custom_data: {
      money_spent: 2500,
      subscription: 'gold',
      accepted_agreement: true,
    },
  },
  signature: '<signature / string>',
});

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>',
  company: '<company 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 protected]';
HelpCrunch('updateUser', { email: userEmail });

userAuth

With the help of userAuth method, you can authorize a customer. This method requires one parameter – ‘user_id’. However, you can add other parameters as well – such as ‘email’, ‘name’, or ‘phone’.

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

Make sure you're passing it as a string.

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', {
  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:

userData: object – custom data
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 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');
}

setLocalization

Call setLocalization 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('setLocalization', 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('setLocalization', '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:

Parameters:

callback (optional): function

HelpCrunch('logout', function(data) {
  if (data && data.success) {
    // do something
  }
});

muteNotificationSound

On some webpages you might not want to interrupt users with chat notification sounds. These might be some conference rooms, classrooms etc... Adding this boolean method will prevent chat sounds from playing ono such pages.

Parameters:

value: boolean

HelpCrunch('muteNotificationSound', true);

setChatButtonOffset

Chat button position on page can be changed dynamically or statically with this API method.

Parameters:

horizontal: number
bottom: number

HelpCrunch('setChatButtonOffset', horizontal, bottom);

setOperatingHours

The general "Operating Hours" setting from all chat widgets is available in Settings. To override this setting for a specific chat widget, 'setOperatingHours' method can be used after the widget code.

HelpCrunch('setOperatingHours', {
  timezone: 'Europe/London',
  hours: {
    monday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    tuesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    wednesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    thursday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    friday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    saturday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
    sunday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
  }
});

The list of timezones you can use with this method:

  'Pacific/Midway', 'Pacific/Honolulu', 'Pacific/Tahiti', 'Pacific/Gambier', 'America/Adak', 'America/Anchorage',
  'America/Metlakatla', 'America/Los_Angeles', 'America/Tijuana', 'America/Chihuahua', 'America/Mazatlan',
  'America/Managua', 'Canada/Saskatchewan', 'America/Mexico_City', 'America/Monterrey', 'America/Lima', 'America/Bogota',
  'America/Caracas', 'America/La_Paz', 'America/Campo_Grande', 'America/New_York', 'Canada/Atlantic', 'America/Santiago',
  'America/Sao_Paulo', 'America/Argentina/Buenos_Aires', 'Canada/Newfoundland', 'America/Godthab', 'America/Noronha',
  'Atlantic/South_Georgia', 'Atlantic/Cape_Verde', 'Atlantic/Azores', 'Africa/Monrovia', 'Africa/Casablanca',
  'Europe/Lisbon', 'Europe/London', 'Africa/Lagos', 'Europe/Amsterdam', 'Europe/Belgrade', 'Europe/Berlin',
  'Europe/Bratislava', 'Europe/Brussels', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Ljubljana', 'Europe/Madrid',
  'Europe/Paris', 'Europe/Prague', 'Europe/Rome', 'Europe/Sarajevo', 'Europe/Skopje', 'Europe/Stockholm', 'Europe/Vienna',
  'Europe/Warsaw', 'Europe/Zagreb', 'Africa/Cairo', 'Africa/Harare', 'Africa/Johannesburg', 'Europe/Athens',
  'Europe/Bucharest', 'Europe/Istanbul', 'Asia/Jerusalem', 'Europe/Helsinki', 'Europe/Kyiv', 'Europe/Riga', 'Europe/Sofia',
  'Europe/Tallinn', 'Europe/Vilnius', 'Asia/Baghdad', 'Asia/Kuwait', 'Europe/Minsk', 'Africa/Nairobi', 'Asia/Riyadh',
  'Europe/Volgograd', 'Europe/Moscow', 'Asia/Muscat', 'Asia/Baku', 'Asia/Tbilisi', 'Asia/Yerevan', 'Asia/Dubai',
  'Europe/Samara', 'Indian/Reunion', 'Asia/Karachi', 'Asia/Tashkent', 'Asia/Yekaterinburg', 'Indian/Maldives',
  'Asia/Kolkata', 'Asia/Almaty', 'Asia/Dhaka', 'Asia/Urumqi', 'Asia/Bangkok', 'Asia/Jakarta', 'Asia/Novosibirsk',
  'Asia/Krasnoyarsk', 'Asia/Hong_Kong', 'Asia/Kuala_Lumpur', 'Australia/Perth', 'Asia/Singapore', 'Asia/Taipei',
  'Asia/Irkutsk', 'Asia/Tokyo', 'Asia/Seoul', 'Asia/Yakutsk', 'Australia/Adelaide', 'Australia/Darwin',
  'Australia/Brisbane', 'Pacific/Guam', 'Australia/Hobart', 'Australia/Melbourne', 'Pacific/Port_Moresby',
  'Australia/Sydney', 'Asia/Vladivostok', 'Asia/Magadan', 'Pacific/Fiji', 'Pacific/Kwajalein', 'Asia/Kamchatka',
  'Pacific/Auckland',

Example of the full widget code, together with operating hours:

<script type="text/javascript">
  window.helpcrunchSettings = {
    organization: 'helpcrunch',
    appId: 'a47f724b-bh1f-4504-7fa7-0fbf7dg84kb0',
    user: {
      user_id: 'userOneHash',
      name: 'User One',
      email: '[email protected]',
      phone: '+380123456789',
      company: 'my company',
      custom_data: {
        is_active: true,
        money_spent: 2500,
        subscription: 'gold',
        accepted_agreement: true,
      },
    },
  };

</script>

<script type="text/javascript">
  (function(w,d){var hS=w.helpcrunchSettings;if(!hS||!hS.organization){return;}var widgetSrc='https://'+hS.organization+'.widget.helpcrunch.com/';w.HelpCrunch=function(){w.HelpCrunch.q.push(arguments)};w.HelpCrunch.q=[];function r(){if (d.querySelector('script[src="' + widgetSrc + '"')) { return; }var s=d.createElement('script');s.async=1;s.type='text/javascript';s.src=widgetSrc;(d.body||d.head).appendChild(s);}if(d.readyState === 'complete'||hS.loadImmediately){r();} else if(w.attachEvent){w.attachEvent('onload',r)}else{w.addEventListener('load',r,false)}})(window, document)

HelpCrunch('setOperatingHours', {
  timezone: 'Europe/London',
  hours: {
    monday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    tuesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    wednesday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    thursday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    friday: {
      is_enabled: true,
      from: "03:00",
      to: "13:00",
    },
    saturday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
    sunday: {
      is_enabled: false,
      from: "03:00",
      to: "13:00",
    },
  }
});
</script>

openKBArticle

To open specific knowledge base articles in chat widget, specific localization

HelpCrunch('openKBArticle', { articleId: 125, lang: 'uk' })

onError

In case of any error in chat widget, this method allows you to react accordingly

HelpCrunch('onError', (error) => {

});

setMediaCSS

Media CSS is useful when you want to modify widget styles by defining specific classes, depending on the browser viewport size.
Standard CSS media queries won’t work properly, as HelpCrunch widget is inside an iframe, it’s important to track the browser viewport size, not the iframe

HelpCrunch('setMediaCSS', {
  maxWidth: {
    800: 'max-width-800-class',
    320: 'max-width-320-class'
  },
  maxHeight: {
    400: 'max-height-400-class'
  }
})

Example:

#helpcrunch-container.max-width-800-class .helpcrunch-status-bar .helpcrunch-widget-icon-wrapper {       
  color: tomato;
}

Did this answer your question?