JavaScript API

Once the HelpHero script loads it makes a global object HelpHero object available to your web page. This allows your to interact with HelpHero from your own scripts, meaning you can start & stop tours, listen to events and more. The following methods are available on the global HelpHero object.

HelpHero.identify(userId, [properties])

Identify the current user with a userId (string or number) and an optional set of user properties (object).

HelpHero.identify("<USER_ID>", {
  name: "<NAME>",
  role: "<USER_ROLE>"
If userId is null or undefined value, the API will fallback to using HelpHero.anonymous(). If you wish to avoid this behaviour please perform a null check before passing the userId to HelpHero.identify
if (userId != null) {


Generates a unique user id which will be persisted in the user’s browser until the browser cache is cleared.


Calling the update method with an object of user properties will update those fields on the current user and then check if any tours should be auto started based on the new properties.

  hasPlan: true

Or pass function to update based on current properties

HelpHero.update(function(currentProperties) {
  return {
    hasPlan: !currentProperties.hasPlan

HelpHero.startTour(tourId, [options])

Starts tour with the specified tour id. The tour will only start if the user is on an URL that matches the starting URL match specified in the tour. How do you find your tourId?

Start tour even if user has already seen tour:


Options you can pass to override the default behaviour of startTour

skipIfAlreadySeen: boolean
redirectIfNeeded: boolean
stepId: string


The current active tour is moved forward one step. Is ignored when current step is a highlight which requires the user to click within highlighted area.


Options you can pass to override the default behaviour of advanceTour

stepId: string | number


The current active tour is immediately cancelled.


Starts checklist with the specified checklist id. The checklist will only start if:

  • The user is on an URL that matches the starting URL match specified in the checklist.
  • All conditions specified for showing the checklist are satisfied.
  • At least one of the checklist items is eligible to be displayed.


Opens the checklist if there is one available for the current page.


Closes the checklist if there is one available for the current page.


Allows you to set HelpHero options by passing an object which can contain any of the following:

show: boolean
showBeacon: boolean
navigate: (url: string) => void

HelpHero.on([eventName], listenerFn, [context])

Register a listener function that will be invoked when tour events occur.
  • tour_started
    A tour has been started either automatically, from a checklist or via the API.
  • tour_completed
    A tour has been completed from start to finish.
  • tour_advanced
    A tour has been advanced to the next step either by the user, by a funnel step or via the API.
  • tour_backtracked
    A tour has backtracked to a previous step either by the user or a funnel step.
  • tour_cancelled
    A tour has been cancelled either by the user or via the API.
  • tour_interrupted
    A tour was interrupted due to user navigating away from the page or because the appropriate element to highlight was not found within the timeout specified.
  • tour_dismissed
    A tour has been dismissed by the user clicking on a special dismiss button.
  • checklist_item_completed
    An item in a checklist has been completed.
  • checklist_completed
    All the items in a checklist have been completed.
Example register listener for specific event:
HelpHero.on("tour_started", function(event, info) {
  console.log(event, info);  
Example register listener for all events:
HelpHero.on(function(event, info) {
  console.log(event, info);  
The listener recieves the following arguments for tour events:
1) event: Event
2) info: Info
The listener recieves the following arguments for checklist events:
1) event: Event
2) info: Info[eventName], listenerFn, [context])

Unregister a previously registered listener. Use the same arguments that you passed when registering the listener with HelpHero.on.