Articles on: OneHash Chat | Website Chat

SDK Setup in OneHash Chat

SDK Setup

Additional information about a contact is always useful. The OneHash Chat Website SDK ensures that you can send additional information that you have about the user.

If you have installed our code on your website, the SDK would expose window.$OneChat object.

In order to make sure that the SDK has been loaded completely, please make sure that you listen to OneChat:ready event as follows:

window.addEventListener('OneChat:ready', function () {
  // Use window.$OneChat here
  // ...

SDK settings

To hide the bubble, you can use the setting mentioned below.

Note: If you use this, then you have to trigger the widget by yourself.

window.OneChatSettings = {
  hideMessageBubble: false,
  position: 'left', // This can be left or right
  locale: 'en', // Language to be set
  type: 'standard', // [standard, expanded_bubble]

Widget designs

OneHash Chat support 2 designs for for the widget

Standard (default)

Expanded bubble

If you are using expanded bubble, you can customize the text used in the bubble by setting launcherTitle parameter on OneHash Chat Settings as described below.

window.OneChatSettings = {
  type: 'expanded_bubble',
  launcherTitle: 'Chat with us'

Enable popout window

Inorder to enable the popout window, add the following configuration to OneChatSettings. This option is disabled by default.

window.OneChatSettings = {
  // ...Other Config
  showPopoutButton: true,

Trigger widget without displaying bubble


// Toggle widget by passing state
window.$OneChat.toggle('open'); // To open widget
window.$OneChat.toggle('close'); // To close widget

Set the user in the widget

window.$OneChat.setUser('<unique-identifier-key-of-the-user>', {
  email: '<>',
  name: '<name-of-the-user>',
  avatar_url: '<avatar-url-of-the-user>',
  phone_number: '<phone-number-of-the-user>',

setUser accepts an identifier which can be a user_id in your database or any unique parameter which represents a user. You can pass email, name, avatar_url, phone_number as params. Support for additional parameters is in progress.

Make sure that you reset the session when the user logs out of your app.

Identity validation using HMAC

To disallow impersonation and to keep the conversation with your customers private, we recommend setting up the identity validation in OneHash Chat. Identity validation is enabled by generating an HMAC(hash based message authentication code) based on the identifier attribute, using SHA256. Along with the identifier you can pass identifier_hash also as shown below to make sure that the user is correct one.

window.$OneChat.setUser(`<unique-identifier-key-of-the-user>`, {
  name: '', // Name of the user
  avatar_url: '', // Avatar URL
  email: '', // Email of the user
  identifier_hash: '', // Identifier Hash generated based on the webwidget hmac_token
  phone_number: '', // Phone Number of the user

To generate HMAC, read identity validation

Note that implementing HMAC authentication will allow chat history to persist across sessions.

Set custom attributes

Inorder to set additional information about the customer you can use customer custom attributes field. Read more about custom attributes here

To set a custom attributes call setCustomAttributes as follows

  accountId: 1,
  pricingPlan: 'paid',

  // Here the key which is already defined in custom attribute
  // Value should be based on type (Currently support Number, Date, String and Number)

You can view these information in the sidepanel of a conversation.

To delete a custom attribute, use deleteCustomAttribute as follows


Set language manually


To set the language manually, use the setLocale function.

Set labels on the conversation

Please note that the labels will be set on a conversation if the user has not started a conversation. In that case, the following items will not have any effect:



Refresh the session (use this while you logout the user from your app)


Widget errors

In order to see any errors in the widget, please make sure that you listen to OneChat:event event as follows:

window.addEventListener('OneChat:error', function () {
  // ...

Note: This feature is available in v2.3.0 or later.

Updated on: 27/09/2023

Was this article helpful?

Share your feedback


Thank you!