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 site's <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

Configuration data options

Options Key

Default Value

Type

Descriptions

data-suggested-article-ids

[]

Array

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

data-always-hide-bubble

false

Boolean

Don't show the widget bubble.

data-hide-subject

false

String

Hide the subject field (subject_prefill must be set)

data-subject-prefill

null

String

Prefill the subject input field

data-text-prefill

null

String

Prefill the text input field

data-open-after-init

false

Boolean

Automatically open the widget after initialization.

data-style

"default"

String

The appearance of the widget. "default" or "modal"

data-z-index

1000

Integer

The css z-index of the widget.

data-offset-top

20

Integer

The top offset of bubble and widget in px.

data-offset-right

20

Integer

The right offset of bubble and widget in px.

data-offset-bottom

20

Integer

The bottom offset of bubble and widget in px.

data-offset-left

20

Integer

The left offset of bubble and widget in px.

data-position

"bottom-right"

String

Position of the widget-bubble on the screen.

data-show-logo

true

Boolean

Show the logo on top of the widget.

HelpWidget('init', config)

If you want full control over the initialization of your widget, use the global HelpWidget() function and remove data-auto-init from our script snippet. (See above)

Note: Using React you may need to use window.HelpWidget() instead of HelpWidget().

// 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

auth

{ 'widget_id': '...', 'client_id': '...', 'token': '...' }

Object

Optional auth object to set the tokens via the config option instead of script tag attributes.

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. "default" or "modal"

z_index

1000

Integer

The css z-index of the widget.

offset_top

20

Integer

The top offset of bubble and widget in px.

offset_right

20

Integer

The right offset of bubble and widget in px.

offset_bottom

20

Integer

The bottom offset of bubble and widget in px.

offset_left

20

Integer

The left offset of bubble and 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.

subject_prefill

null

String

Prefill the subject input field

text_prefill

null

String

Prefill the text input field

hide_subject

false

Boolean

Hide the subject field (subject_prefill must be set)


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

Note: Using React you may need to use window.HelpWidget() instead of HelpWidget().

// 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 },
           },
   }
});

Load Widget Script Dynamically

In order to load the Widget script dynamically, you can use the code below. Make sure you put in your token, client ID and widget ID. This approach can be helpful when using frameworks like svelte or stimulusJS.

    var script = document.createElement( 'script' ),
        head = document.head || document.getElementsByTagName( 'head' )[ 0 ];
    script.src = 'https://cdn.helpspace.com/widget/widget-v1.js';
    script.setAttribute( "data-auto-init", "" );
    script.setAttribute( "id", "helpspace-widget-script" );
    script.async = false; // optionally

    script.setAttribute( "data-token", "YOUR TOKEN" );
    script.setAttribute( "data-client-id", "YOUR CLIENT ID" );
    script.setAttribute( "data-widget-id", "YOUR WIDGET ID" );
    
    head.insertBefore( script, head.firstChild );

© HelpSpace 2024
Powered by Powered By HelpSpace