Documentation

Widget Javascript API

Control your widget programmatically

Loading our widget JavaScript library provides a few nifty methods to control the appearance and behavior of the widget programmatically.Placing the JavaScript snippet between your sites <head></head> tags will automatically initialize and load your widget as soon as your website is fully loaded.

<script
  id="helpspace-widget-script"
  data-auto-init
  data-token="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-client-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-widget-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  src="https://cdn.helpspace.com/widget/widget-v1.js" 
  async>
</script>
The async attribute is needed to load the widget after your site has been fully loaded and rendered.

Manually initialize your widget

In order to control when and how the widget gets initialized, you need to remove
the data-auto-init attribute from the script. This will stop the widget from automatically initialize after the script has been loaded. In some cases, you also need to change async to defer. Your script should then look like the one below:

<script
  id="helpspace-widget-script"
  data-token="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-client-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-widget-id="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  src="https://cdn.helpspace.com/widget/widget-v1.js" 
  defer> 
</script>
// removed data-auto-init
// async changed to defer

HelpWidget('init', config)

Now you have full control over the initialization of your widget using the global HelpWidget() function.

// let's wait until the script is loaded
window.addEventListener("load", function() {

   let config = {
      disable_docs: true,
      suggested_article_ids: [1,3,6]
      ...
   };
   HelpWidget('init', config);

});


Configuration options

Options Key

Default Value

Type

Descriptions

sites

[]

Array

An array of IDs of your docs sites the widget should search through.

disable_docs

false

Boolean

Don't show the docs area.

disable_contact

false

Boolean

Don't show the contact form.

suggested_article_ids

[]

Array

An array of IDs of your articles you want to highlight on the docs view.

always_hide_bubble

false

Boolean

Don't show the widget bubble.

open_after_init

false

Boolean

Automatically open the widget after initialization.

style

"default"

String

The appearance of the widget.

z_index

1000

Integer

The css z-index of the widget.

offset_top

20

Integer

The top offset of the widget in px.

offset_right

20

Integer

The right offset of the widget in px.

offset_bottom

20

Integer

The bottom offset of the widget in px.

offset_left

20

Integer

The left offset of the widget in px.

position

"bottom-right"

String

Position of the widget bubble on the screen.

show_logo

true

Boolean

Show the logo on top of the widget.

logo

""

String

A URL to your logo image.

logo_alt

""

String

Logo image alt text.

bubble_icon

"message"

String

Bubble icon.

docs_icon

"books"

String

Docs icon.

contact_icon

"paperplane"

String

Contact icon.

language

"en"

String

Language of the widget.

colors

[bubble_background: '#dddddd', ...]

Array

A keyed array of colors. See the full list of available color options below.

sizes

{ default: Article: {width:450, height: 550}
}

Object

Overwrite sizes of the widget and modal screen. See Sizing Options for more info.


Color Customization

The widget colors are defined within an extra array called 'colors':

let config = {
   disable_docs: true,
   suggested_article_ids: [1,3,6]
   colors: [
       bubble_background: 'linear-gradient(45deg,#483fb9,#1e91b5)'
       ...
   ]
};
HelpWidget('init', config);

Available color options

Options Key

Default Value

Type

Descriptions

bubble_background

"linear-gradient(45deg, #483fb9, #1e91b5)"

String

The color value for the widget bubble background.

header_background

"linear-gradient(-10deg, rgb(25, 152, 181), rgb(73, 60, 185))"

String

The color of the header background.

header_text

"#ffffff"

String

The color of the header text.

header_icons

"#ffffff"

String

The color of the header icons at the very top (back and close).

button_background

"#395fb7"

String

The color of the button background.

button_text

"#ffffff"

String

The color of the button text.

Widget API Functions

// Open widget
HelpWidget('open');

// Close widget
HelpWidget('close');

// Change suggested articles without opening the widget
HelpWidget('suggestions', [1,2,4]);

// Prefill the search field
HelpWidget('search', 'your search string');

// Open Widget in modal mode
HelpWidget('open', { modal: true } );

// Open Widget and Article with id 123
HelpWidget('open', { article: 123 } );

// Open Widget in modal mode and go to article with id 123
HelpWidget('open', { modal: true, article: 123 } );

// Open Widget and go to contact
HelpWidget('open', { contact: true } );

// Open Widget and go to docs
HelpWidget('open', { docs: true } );

// Open Widget, go to docs and search for something
HelpWidget('open', { search: 'search for something' } );

// Set user data to prefill the contact form
HelpWidget('user', {
   name: 'Peter Fox',
   email: 'example@example.com',
   id: 123, // optional
   show: false // hide name and email fields on contact form
});

Link Data Attributes

You can control your widget from within your site using normal links and predefined data-widget-* attributes:

<a href="#" data-widget-open>Open widget</a>

<a href="#" data-widget-close>Close widget</a>

<a href="#" data-widget-open data-widget-contact>Open contact</a>

<a href="#" data-widget-open data-widget-docs>Open docs</a>

<a href="#" data-widget-open data-widget-article="2">Open article with ID 2</a>

<a href="#" 
   data-widget-open 
   data-widget-docs 
   data-widget-suggestions="1,2,4"
>Open docs with certain suggestion IDs</a>

<a href="#" 
   data-widget-open 
   data-widget-modal 
   data-widget-article="2"
>Open Article with ID 2 in modal</a>

<a href="#" 
   data-widget-open 
   data-widget-search="your search string"
>Open docs search</a>

Sizing Options

You can define the size of every component individually using the sizes config option:

HelpWidget( 'init', {
    sizes: {
           default: {
              Article: { width: 450, height: 550 },
              Main: { width: 350, height: 550 },
           },
           modal: {
              Main: { width: 450, height: 600 },
              Article: { width: 800, height: 1024 },
              Docs: { width: 800, height: 1024 },
              Contact: { width: 450, height: 600 },
           },
   }
});