Controlling the widget from the page

Commands from the site #

The widget puts a window.WidgetChat object on the page. Use it to open and close the window, show an invitation and subscribe to events. Do not rely on our markup ids: they are internal and change.

<button id="ask">Message us</button>
<script>
  document.getElementById('ask').addEventListener('click', function () {
    WidgetChat.open({ message: 'A question about delivery' })
  })
</script>

The button is clicked before the widget loads #

The widget file loads asynchronously, so for the first seconds the object is not on the page yet. If your button can be clicked during that time, declare a queue stub before the widget snippet: the widget picks it up at start and runs the collected commands.

<script>
  window.WidgetChat = window.WidgetChat || { q: [] };
  ['open', 'close', 'toggle', 'showInvite', 'hideInvite', 'attention'].forEach(function (name) {
    WidgetChat[name] = WidgetChat[name] || function () {
      WidgetChat.q.push([name, [].slice.call(arguments)]);
    };
  });
</script>

A queued command runs once, when the window is built. There is no need to repeat it.

Events #

Every event arrives two ways: in a WidgetChat.on('name', fn) handler and on window as widgetchat:name. The second one is handy when your code runs before the widget or lives in another script.

window.addEventListener('widgetchat:sent', function (event) {
  if (event.detail.first) console.log('first conversation from this page')
})

Invitation to a conversation #

After the given delay a bubble with your text appears next to the button, and the button starts calling for attention. Clicking the bubble opens the chat, the cross dismisses it.

By default the widget stays silent. The invitation is switched on in the dashboard, on the “Appearance” step, together with its delay and text. Attributes on the script tag win over the dashboard setting: use them to invite earlier and in different words on a particular page, a checkout for example.

<script async
  src="https://api.widgetchat.ru/widget/bozex-support-widget.js"
  data-widget-id="wc_9qA…Lk"
  data-invite-delay="15"
  data-invite-text="We can help with stock and delivery dates"
></script>

The invitation shows once per tab and never on top of an open chat or a fresh reply. A dismissal is remembered for the visit; until the visitor opens the chat the widget writes nothing to the browser.

Goals for analytics #

The widget sends goals to the counters already present on the page: Yandex.Metrica via reachGoal, Google Tag Manager via dataLayer and gtag. The counter number is not needed — Metrica knows its own counters. In the Metrica dashboard create the goal as a JavaScript event with the same identifier.

<script async
  src="https://api.widgetchat.ru/widget/bozex-support-widget.js"
  data-widget-id="wc_9qA…Lk"
  data-metrika-id="12345678"
  data-goals="off"
></script>

data-metrika-id is only needed when the page carries several counters and the goals must go to a particular one. data-goals="off" turns the sending off completely.