Widget documentation

How it is built#

Two pieces land on your page, and knowing which is which explains most of the API.

The loader is a few kilobytes of vanilla JavaScript served from /widget/v1.js. It draws the launcher button inside a shadow root, so none of your CSS reaches it and none of its CSS reaches you, and it creates the chat window as an iframe. It owns the launcher’s colour, icon, side of the screen, the unread badge, and the tab-title flicker.

The frame is the chat application itself, served from your Connect host at /widget/frame.html and running cross-origin inside that iframe. Conversations, help articles, uploads, and the visitor’s session all live in there. Because it is a different origin, your page’s JavaScript cannot read a single message a visitor sends — that is the point of the arrangement, not a limitation of it.

The two talk over postMessage with both origins pinned. Your page talks to both of them through one global queue, $connect.

<script>
  window.$connect = window.$connect || [];
  window.CONNECT_WEBSITE_KEY = "wk_xxxxxxxxxxxxxxxxxxxxxxxx";
  (function () {
    var s = document.createElement("script");
    s.src = "https://<your-connect-host>/widget/v1.js";
    s.async = 1;
    document.head.appendChild(s);
  })();
</script>

Where a setting lives#

Settings split cleanly in two, and it is worth knowing which half you are in before you go looking for a knob.

• Dashboard settings are stored per website and arrive with every boot. Colour, theme, launcher icon, side, team name, the greeting, the proactive nudge, the feature toggles, and the origin allowlist all live at Websites → your site in the app. Change one and every visitor sees it on their next page load — no redeploy of your site.
• Page settings are things only your site knows: who this visitor is, what plan they are on, what is in their cart, which functions an agent may run in their browser. Those are pushed from your own JavaScript through $connect.

There is no third category. If a value depends on the visitor it goes through the JavaScript API; if it is the same for everyone it belongs in the dashboard.

The pages#

Read in order if you are installing for the first time. Jump straight to Use cases if you already have it running and want to make it do something specific.