Helpshift APIs

Open Widget

If you want to open the conversation window at any time (apart from an explicit user click on launcher button), you can do it by calling the following API. This could be useful for triggering proactive help.

Helpshift("open");

Close Widget

Similarly, for closing the conversation window at any time, you can call the following API.

Helpshift("close");

Hide Widget

You can hide Web Chat completely (both the launcher and the widget) by calling the following API.

Helpshift("hide");

You may want to use this API when you do not want to show the widget on specific pages or to specific users.

Show Widget

You can have Web Chat (both the launcher and the widget) re-appear after it was previously hidden (via the hide API) by calling the following API.

Helpshift("show");

This API will restore the visibility of Web Chat after it was previously hidden. For example, if the widget was open before hideAPI was called, then show API will display the widget in the open state. This API retains the visibility behavior.

Visibility States

Update Helpshift Config

If you want to update the helpshiftConfig object after your web page has loaded, you can do it by calling the following API

Helpshift("updateHelpshiftConfig");

This API is best for use with single page web applications.

Example: In a single page application, if you are retrieving user related data after login, to pass that updated user data to Web Chat, you should update the global helpshiftConfig object with the user data and call the above API.

// Initial helpshift config object during page load
helpshiftConfig = {
    platformId: "<YOUR_PLATFORM_ID>",
    domain: "<YOUR_DOMAIN>",
    .
    .
};
.
.
.
// After user login, you can update the user data in config object.
helpshiftConfig.userId = "<LOGGED_IN_USER_ID>";
Helpshift("updateHelpshiftConfig");

Make sure you do not overwrite the helpshiftConfig object when trying to update it.

  1. This API is applicable to all the helpshiftConfig object options, such as user related data, language, full privacy, widgetOptions, etc.
  2. Once the conversation has started, calling this API will not update the user identity or update Custom Issue Fields for an ongoing conversation.
  3. This API will cause the widget to reload. If the user has opened the widget and this API is called, then the user will see the loading indicator, and the conversation of the updated user will be displayed.

Widget Options

To configure the widget's behavior, you'll need to add widgetOptions to the Embed Code. All of the widget specific options go here.

(function () {
  // The following part remains as it is in the Embed Code.
  // Please check the part after "Widget Options Start"
  var PLATFORM_ID = "<YOUR_PLATFORM_ID>",
      DOMAIN = "<YOUR_DOMAIN>";

  window.helpshiftConfig = {
    platformId: PLATFORM_ID,
    domain: DOMAIN
  };

  /* Widget Options Start */
  helpshiftConfig.widgetOptions = {
    // All widget specific options go here.
  };
  /* Widget Options End */
}) ();

Enable Fullscreen View for Pop-ups

If you want to open the widget in full screen mode on a non-mobile device, you can pass through the fullScreen option in widgetOptions.

helpshiftConfig.widgetOptions = {
  // ...
  fullScreen: true
};

On mobile devices and on low resolution tablets and desktops, the widget will open in full screen mode.

Show/Hide Launcher

You can hide the default launcher and use your own launcher. You can control opening and closing of the conversation window using the open and close APIs. Add the following option in widgetOptions to hide the default launcher.

helpshiftConfig.widgetOptions = {
  // ...
  showLauncher: false
};

Widget Position

To set the widget's position, provide the position option in widgetOptions. Values allowed for position are:

  • bottom-right
  • bottom-left
  • top-left
  • top-right

The default value is bottom-right.

helpshiftConfig.widgetOptions = {
  // ...
  position: "bottom-left"
};

Widget z-index

By default, Web Chat assigns a large z-index value to its widget (the launcher and conversation window). If you want to use a custom value of z-index for Web Chat, you can do so by setting the zIndex option in widgetOptions. You can only use a number with this option.

helpshiftConfig.widgetOptions = {
  // ...
  zIndex: 50
};

Set Initial User Message

If you want to set the initial user message through an API rather than making the end user type it, you can use the following API.

var userMessage = "Hello, how can I track my order?"
Helpshift("setInitialUserMessage", userMessage);

Events

The Helpshift widget fires the following events across different scenarios. You can use the addEventListener and removeEventListener APIs to manage the events.

Chat End Event

This event gets fired when the user clicks on the "Close" button after the chat is resolved. To listen to this event, add the following code after the embed code.

The "Close" button is visible only for chat flows where the setInitialUserMessage API is used.

Adding the chatEnd event handler

var chatEndHandler = function() {
  console.log("Chat ended");
};
Helpshift("addEventListener", "chatEnd", chatEndHandler);

Removing the chatEnd event handler

Helpshift("removeEventListener", "chatEnd");

New Unread Messages Event

This event gets fired when there are new unread message for the user. To listen to this event, add the following code after the embed code.

This event can also be used to show a browser notification when the unread messages count changes.

More info on Browser notifications

Adding the new unread messages event handler

var newUnreadMessagesEventHandler = function(data) {
  console.log("Unread count = ", data.unreadCount);
}
Helpshift("addEventListener", "newUnreadMessages", newUnreadMessagesEventHandler);

Removing the new unread messages event handler

Helpshift("removeEventListener", "newUnreadMessages", newUnreadMessagesEventHandler);

User Changed Event

This event gets fired when the user reopens Web Chat by clicking on the email link, if we detect that the user's identifier has changed from when the original user started the conversation to when this user clicked the email link.

The ‘Follow up via email’ toggle for Web Chat needs to be enabled for you to use this event. The User Changed event can be used to build an optimal user experience for cases where the user’s identifier has changed after clicking the link, such as in the following scenarios: 1. The user started chat anonymously (didn’t login when they were chatting), but logged in before clicking on the link. 2. The user started chat as a logged-in user but logged out before clicking the link. 3. The user started chat as a logged-in user but logged in as a different user before clicking the link.

Adding the User Changed event handler

var userChangedHandler = function(data) {
  console.log("User's original state is: " + data.originalState);
  console.log("User was having conversation on: " + data.pageUrl);
};
Helpshift("addEventListener", "userChanged", userChangedHandler);

Removing the User Changed event handler

Helpshift("removeEventListener", "userChanged", userChangedHandler);

Using the values returned by the event

Name Values How to use
originalState (this is the user’s state when they started chat) logged-in If the user was originally logged-in, you should prompt the user to login again. As long as the user’s login credentials are same as their credentials when they started the chat, they’ll be able to resume their conversation.
anonymous If the user was originally anonymous (aka not logged-in), you should prompt the user to logout or automatically log them out so that they are able to resume their conversation.
pageUrl The page where the user had started the chat We highly recommend taking the user to the page where they started the chat after they successfully logout or login (based on what their original state was), so that they are taken back to the page with the right context.

We also recommend using the Open Widget API to automatically open the widget for users after a successful login/logout (depending on what their original state was.)