OpenWidget JavaScript API

Introduction

What is JS API?

OpenWidget JavaScript API lets you interact with the widget added to your website in ways that are not possible by default. For example, it is useful if you want to change the default OpenWidget launcher to a custom one on your mobile website and trigger the maximized view only when a customer clicks a specific button. Or if you'd like to create a custom button that will direct your customer straight to FAQ or one of our forms: Contact, Feedback or Bug Form.

Our JS API documentation focuses on developers and requires a basic knowledge of JavaScript and HTML. However, when designing both our APIs and documentation, we wanted to ensure that you'll be able to easily create custom ways to interact with OpenWidget. Along the way, you can expect some ready-made examples to back up the raw technical descriptions.

You will also get familiar with our HTML Attributes – a great way to create a simple widget integration without writing a single line of code.

Getting started

Once OpenWidget is installed on your website, our JS API can be accessed via the OpenWidget object, as it is being initialized within OpenWidget's tracking code. If you have not yet installed it on your website, you can get the code directly from the application. Here's how the OpenWidget's code looks like:

<!-- Start of OpenWidget (www.openwidget.com) code -->
<script>
  window.__ow = window.__ow || {};
  window.__ow.organizationId = "yourOrganizationId";
  ;(function(n,t,c){function i(n){return e._h?e._h.apply(null,n):e._q.push(n)}var e={_q:[],_h:null,_v:"2.0",on:function(){i(["on",c.call(arguments)])},once:function(){i(["once",c.call(arguments)])},off:function(){i(["off",c.call(arguments)])},get:function(){if(!e._h)throw new Error("[OpenWidget] You can't use getters before load.");return i(["get",c.call(arguments)])},call:function(){i(["call",c.call(arguments)])},init:function(){var n=t.createElement("script");n.async=!0,n.type="text/javascript",n.src="https://cdn.openwidget.com/openwidget.js",t.head.appendChild(n)}};!n.__ow.asyncInit&&e.init(),n.OpenWidget=n.OpenWidget||e}(window,document,[].slice))
</script>
<noscript>You need to <a href="https://www.openwidget.com/enable-javascript" rel="noopener nofollow">enable JavaScript</a> to use the communication tool powered by <a href="https://www.openwidget.com/" rel="noopener nofollow" target="_blank">OpenWidget</a></noscript>
<!-- End of OpenWidget code -->

The OpenWidget object is equipped with the following functions: on – it registers a callback function for a specific event; call – it allows you to invoke methods available in our JS API.

The pattern of using those functions looks like this:

OpenWidget.function(method, data)

and here's a simple example of how it looks like in real life:

OpenWidget.call('maximize', { feature: 'faq' })

In this case, calling the maximize method with feature faq passed as an object will maximize your OpenWidget, with the FAQ view displayed upfront.

Developers Guides

Even with dedicated JS API documentation, seeing a live example can sometimes explain more than just looking at raw data. That's why we prepared Developers Guides that will tell you how to implement some of our features on your website or within your app.

Available guides:

• Asynchronous Initialization Guide
• HTML Attributes Guide

Methods

Our JS API allows you to interact with your OpenWidget with the use of the following methods:

• minimize
• maximize
• hide
• destroy

Below you will find a description of each method that is available for you to use.

Minimize

It minimizes the maximized view (OpenWidget’s Home Screen) of your OpenWidget.

Example:

OpenWidget.call('minimize')

Maximize

It maximizes the minimized view (OpenWidget’s launcher) of your OpenWidget.

Example:

OpenWidget.call('maximize')

When maximizing the widget, you can also pass over the feature: "feature_name" as an object in the function's argument. It allows your customers to maximize the widget with a specific feature displayed in a dedicated view. For example, it may come in handy if you prepare a dedicated button that will ask your customers to reach out via the Contact Form. Here's the list of features that you can pass as a value for the feature argument:

• chat
• faq
• form-contact
• form-feedback
• form-bugreport

Example:

OpenWidget.call('maximize', { feature: 'form-contact' })

You can enhance the 'chat' feature by including an optional messageDraft parameter. This parameter pre-fills the chat input field with a predefined message.

Example:

OpenWidget.call('maximize', {
  feature: 'chat',
  messageDraft: 'Hello, I need help!',
})

The action will have no effect if the widget's current state prevents message entry or if the user already has a message draft.

Hide

It hides both minimized and maximized views of OpenWidget on your website. To bring it back later on, you will need to use either maximize or minimize API calls.

Example:

OpenWidget.call('hide')

Destroy

It destroys OpenWidget, meaning that it won't be available for your customers to interact with unless they refresh the page or the OpenWidget.init() function is called.

Example:

OpenWidget.call('destroy')

Callbacks

Callbacks allow you to react to specific events triggered by OpenWidget. With their help, you can introduce custom behaviors when OpenWidget triggers a specific event. For example, whenever OpenWidget is ready, you can decide to maximize it automatically. To do that, you need to subscribe to a callback using our JS API.

Example:

function onReady() {
  // add actions that you'd like to perform when OpenWidget is ready
  // for example:
  OpenWidget.call('maximize')
}

OpenWidget.on('ready', onReady)

Available callbacks:

• on ready

On ready

On ready callback is called when the OpenWidget is loaded. If it was loaded already, the provided handler function would be called immediately.

Example:

OpenWidget.on('ready', onReady)

Async Initialization

💡 If you want to learn more about Async Init, click here to check out our official guide that will tell you how to implement it and what are the typical use cases when it may come in handy.

What is AsyncInit?

At OpenWidget, we also have the option to initialize your OpenWidget asynchronously – it allows you to decide exactly how and when the widget should be loaded on your website or within your app. A good example would be loading OpenWidget only when the customer accepts cookies.

How to use it?

As an optional feature, Asynchronous Initialization is disabled by default – whenever customers visit your website, OpenWidget loads automatically just after the snippet code is executed. To enable it, you need to explicitly add the __ow.asyncInit to your OpenWidget’s snippet and set its property to true. Here's a real-life example of how OpenWidget’s snippet with the asyncInit enabled looks like:

window.__ow = window.__ow || {}
window.__ow.organizationId = 'organizationId'
window.__ow.asyncInit = true
;(function (n, t, c) {
  function i(n) {
    return e._h ? e._h.apply(null, n) : e._q.push(n)
  }
  var e = {
    _q: [],
    _h: null,
    _v: '2.0',
    on: function () {
      i(['on', c.call(arguments)])
    },
    once: function () {
      i(['once', c.call(arguments)])
    },
    off: function () {
      i(['off', c.call(arguments)])
    },
    get: function () {
      if (!e._h)
        throw new Error("[OpenWidget] You can't use getters before load.")
      return i(['get', c.call(arguments)])
    },
    call: function () {
      i(['call', c.call(arguments)])
    },
    init: function () {
      var n = t.createElement('script')
      ;(n.async = !0),
        (n.type = 'text/javascript'),
        (n.src = 'https://cdn.openwidget.com/openwidget.js'),
        t.head.appendChild(n)
    },
  }
  !n.__ow.asyncInit && e.init(), (n.OpenWidget = n.OpenWidget || e)
})(window, document, [].slice)

From now on the snippet itself will be executed, but the OpenWidget and its resources will not be loaded. It means that although you will have access to the OpenWidget object, the widget itself will not be present on your website, and the ready callback will not be triggered. With AsyncInit enabled, you can trigger OpenWidget later on when the need arises. To do that, simply call the init function from the OpenWidget object, and your widget will become available:

OpenWidget.init()

Important: note that when the AsyncInit option is enabled and the OpenWidget is not initialized, features like our Visitor Counter or AI-based Product Recommendations will not be triggered and will be available only in maximized view!

HTML Attributes

💡 To learn more about our Attributes and how to add a button with a custom interaction for your WordPress-based website, click here to check out our official HTML Attributes guide.

What are those?

HTML Attributes are OpenWidget-related parameters that you can add to the elements of your website, like buttons. Just like the JS API methods described above, they allow you to interact with OpenWidget added to your service. It's a great way to create custom OpenWidget interactions without knowing even the basics of JavaScript.

For example, suppose you have a dedicated Contact Page on your website/within your app. In that case, you can add a custom Send Us a Message button that, using our HTML Attributes, will maximize the widget with the Contact Form already opened.

Here are some other use-case scenarios where using a custom button to open the widget can be beneficial:

• Maximizing OpenWidget with a specific feature already opened: with the use of HTML Attributes, you can create custom buttons that will instantly maximize the OpenWidget with a feature of your choice opened in a dedicated view. It's a great way to redirect your customers straight to a Contact Form or give them the option to report a bug directly within your application.

• Replacing the default widget launcher with a custom one: if the minimized bubble (OpenWidget's launcher) covers the essential part of your mobile website, you can turn it off inside the OpenWidget application and then create a custom button that your customers can use to maximize the widget for themselves. It is especially useful within mobile apps, where every inch of a screen's working area matters.

Attributes Structure

The structure of HTML Attributes is very simple. We have introduced two parameters:

• data-openwidget-action
• data-openwidget-feature*

Once added to your custom buttons, they will trigger a specific action and open a specific feature in a dedicated view.

*Important: note that the data-openwidget-feature parameter is optional and will work only with the data-openwidget-action set to maximize.

Example:

<button
  type="button"
  data-openwidget-action="maximize"
  data-openwidget-feature="form-contact"
>
  Click Me!
</button>

Available actions

The data-openwidget-action parameter can be combined with the following actions:

• minimize
• maximize

HTML Minimize

It minimizes OpenWidget.

Structure:

data-openwidget-action="minimize"

Example:

<button type="button" data-openwidget-action="minimize">Click Me!</button>

HTML Maximize

It maximizes OpenWidget.

Structure:

data-openwidget-action="maximize"

Example:

<button type="button" data-openwidget-action="maximize">Click Me!</button>

When using the maximize action, you can also combine it with the data-openwidget-feature parameter. It will allow you to maximize OpenWidget with a specific feature displayed in a dedicated view. Here's the list of features that you can combine with maximize action:

• chat
• faq
• form-contact
• form-feedback
• form-bugreport

Example:

<button
  type="button"
  data-openwidget-action="maximize"
  data-openwidget-feature="form-contact"
>
  Click Me!
</button>