Installing the SDK

Having additional information about a contact is always useful. The Hoory Website SDK ensures that you can send additional information that you have about a user.

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

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

window.addEventListener("hoory:ready", function () {
  // Use window.$hoory here
  // ...
});

If you would like to listen to the messages in the widget you can use the following event.

window.addEventListener("hoory:on-message", function (e) {
  console.log("hoory:on-message", e.detail);
});

SDK Settings

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

Note: If you use this, then you’ll also have to trigger the widget.

window.hoorySettings = {
  hideMessageBubble: false,
  position: "left", // This can be left or right
  locale: "en", // Language to be set
  useBrowserLanguage: false, // Set widget language from user's browser
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  avatar: "YOUR_BUBBLE_CHAT_AVATAR", // URL address
  lazyLoad: false, // Set to true if you want to lazy load the widget
  forceManualLinkManagement: false, // Set to true if you want to manage the links manually
  escapeUnreadView: true, // Set to false if you want to have a minimal unread view
  autoOpenUnreadConversation: false, // Set to true if you want the widget to open and switch to the unread conversation automatically
};

Note: be careful using forceManualLinkManagement as it will disable the automatic link handling in the chat widget and you will have to handle the links manually by listening to the hoory:on-link-click event.

window.addEventListener("hoory:on-link-click", function (event) {
  console.log("Link clicked", event.detail);

  // Your custom logic here to handle the link click
  window.location.href = event.detail.href;
});

Possible language values

Value	Language	Value	Language	Value	Language
ar	Arabic	bg	Bulgarian	ca	Catalan
cs	Czech	da	Danish	de	German
el	Greek	en	English	es	Spanish
fa	Persian	fi	Finnish	fr	French
he	Hebrew	hi	Hindi	hr	Croatian
hu	Hungarian	hy	Armenian	id	Indonesian
is	Icelandic	it	Italian	ja	Japanese
ka	Georgian	ko	Korean	lt	Lithuanian
lv	Latvian	ml	Malayalam	ms	Malay
ne	Nepali	nl	Dutch	no	Norwegian
pl	Polish	pt	Portuguese	pt_BR	Brazilian Portuguese
ro	Romanian	ru	Russian	sh	Serbo-Croatian
sk	Slovak	sr	Serbian	sv	Swedish
ta	Tamil	th	Thai	tr	Turkish
uk	Ukrainian	ur	Urdu	ur_IN	Urdu (India)
vi	Vietnamese	zh	Chinese	zh_CN	Chinese (Simplified)
zh_TW	Chinese (Traditional)

Use browser language in your live chat widget automatically

To show the live chat widget in the user's browser locale, set the useBrowserLanguage to true in the window.hoorySettings mentioned above.

Note: If useBrowserLanguage is set to true, The locale mentioned will be ignored. If the browser language is not supported by hoory, the locale mentioned under locale will be used. If that's also missing, the widget will fall back to the locale of the agent dashboard.

Dark Mode

Hoory live-chat widget supports dark mode from v2.4.0. To enable the dark mode, follow the steps mentioned here.

Widget Designs

Hoory supports two designs for the widget.

1. Standard (default)

2. Expanded bubble

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

window.hoorySettings = {
  type: "expanded_bubble",
  launcherTitle: "Chat with us",
};

Enable Popout Window

In order to enable the popout window, add the following configuration to hoorySettings. This option is disabled by default.

window.hoorySettings = {
  // ...Other Config
  showPopoutButton: true,
}

You can also popout the chat window programatically with the `popoutChatWindow()` method.

Programatically Open the Popout Window

You can open the popout window programatically with the popoutChatWindow() method.

To initiate this, call the method like below.

window.$hoory.popoutChatWindow();

Toggle the Widget Bubble Visibility

If you want to hide/show the Hoory widget bubble, you can do so with toggleBubbleVisibility('show/hide')

Example

window.$hoory.toggleBubbleVisibility("show"); // to display the bubble
window.$hoory.toggleBubbleVisibility("hide"); // to hide the bubble

Trigger Widget Without Displaying Bubble

window.$hoory.toggle();

// Toggle widget by passing state
window.$hoory.toggle("open"); // To open widget
window.$hoory.toggle("open:last-conversation"); // To open widget with last conversation view
window.$hoory.toggle("open:new-conversation"); // To open widget with new conversation view
window.$hoory.toggle("close"); // To close widget

Set the User in the Widget

window.$hoory.setUser("<unique-identifier-key-of-the-user>", {
  email: "<[email protected]>",
  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 Hoory. 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.$hoory.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
  description: "", // description about the user
  country_code: "", // Two letter country code
  city: "", // City of the user
  company_name: "", // company name
  social_profiles: {
    twitter: "", // Twitter user name
    linkedin: "", // LinkedIn user name
    facebook: "", // Facebook user name
    github: "", // Github user name
  },
});

To generate HMAC, read identity validation

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

Set Custom Attributes

For a contact

In order 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

window.$hoory.setCustomAttributes({
  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

window.$hoory.deleteCustomAttribute("attribute-key");

For a conversation

You can also set custom attributes for the active conversation from the SDK. To set the custom attributes, call setConversationCustomAttributes as follows.

window.$hoory.setConversationCustomAttributes({
  productName: "iPhone",
  productCategory: "Smartphone",
});

You can view this information in the side panel of a conversation.

To delete a custom attribute, use deleteConversationCustomAttribute as follows.

window.$hoory.deleteConversationCustomAttribute("productName");

Set Language Manually

window.$hoory.setLocale("en");

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:

window.$hoory.setLabel("support-ticket");

window.$hoory.removeLabel("support-ticket");

Refresh the Session (use this while logging the user out from your app)

window.$hoory.reset();

Re-Initialize the widget

If you want to re-initialize the widget with a different website token, you can do so by calling the reRun method as follows:

window.hoorySDK.reRun({
  websiteToken: "YOUR_NEW_WEBSITE_TOKEN",
  baseUrl: BASE_URL, // mostly https://app.hoory.com
});

If you have a different widget config for new website token, you can pass it as follows:

window.hoorySettings = {
  position: "right",
  type: "expanded_bubble",
  launcherTitle: "Chat with us",
};
window.hoorySDK.reRun({
  websiteToken: "YOUR_NEW_WEBSITE_TOKEN",
  baseUrl: BASE_URL, // mostly https://app.hoory.com
});

Conversation open

When the conversation page opens, we are triggering an event so you can get current conversation information.

window.addEventListener("hoory:on-conversation-open", function (event) {
  console.log("Conversation:", event.detail);
});

Conversation Resolved

When the conversation is resolved, we are triggering an event so you can get the conversation information.

window.addEventListener("hoory:on-conversation-resolved", function (event) {
  console.log("Conversation:", event);
});

Show Conversation

This method enables navigation to a specific conversation using its unique conversationId.

window.$hoory.showConversation(123);

Widget Errors

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

window.addEventListener("hoory:error", function () {
  // ...
});

Second Widget (beta)

If you have a second widget on your page, you can run runSecond function from hoorySdk as follows:

<script>
  window.hoorySettings = {
    position: "right",
    type: "standard",
    launcherTitle: "Chat",
  };
  (function (d, t) {
    var BASE_URL = "http://localhost:3000";
    var g = d.createElement(t),
      s = d.getElementsByTagName(t)[0];
    g.src = BASE_URL + "/packs/js/sdk.js";
    g.defer = true;
    g.async = true;
    s.parentNode.insertBefore(g, s);
    g.onload = function () {
      window.hoorySDK.run({
        websiteToken: "mdtjpTPPKFSqCR9J2ZPkXyVi",
        baseUrl: BASE_URL,
      });
      window.hoorySDK.runSecond({
        websiteToken: "xiyRV4NwchjQ22X67quy8Q5o",
        baseUrl: BASE_URL,
        settings: {
          position: "left",
          type: "standard",
          launcherTitle: "Chat",
        },
      });
    };
  })(document, "script");
</script>

You can use the runSecond function to initialize the second widget. Keep it in mind that the run function will initialize the first widget, and it is also recommended to use the run function to initialize the widget. Widget position needs to be set in the settings parameter and it shouldn't be same as the first widget.

After running the runSecond function, you can listen to hoory:* events as with window.hoorySecondWindow like this:

window.hoorySecondWindow.addEventListener("hoory:on-message", () => {
  console.log("message received");
});

also all other APIs for SDK will be available in window.$hoory2.

Full lazy loading (beta)

If you want to lazy load the widget, you can pass lazyLoad as true in the window.hoorySettings mentioned above. This will load only the widget launcher button and not the actual widget. Also while the widget is not fully loaded, you will not be able to use the widget APIs and campaigns, so if user doesn't click on the widget launcher button, the widget will be loaded automatically within 12 seconds.

window.hoorySettings = {
  ...otherSettings,
  lazyLoad: true,
};