JavaScript API

The widget exposes a small global API on window so your page can drive it — open it from your own "Chat with us" button, hide it on certain routes, or tell it who the visitor is.

These globals are installed as soon as widget.iife.js runs. Because the script loads async, guard your calls so they don't run before it's ready.

window.__konvoai — controlling the widget

window.__konvoai is an object with six methods:

Calls are idempotent and safe to repeat. hide() removes the widget from view without ending the visitor's session; show() brings it back in the same state.

Open the widget from your own button

<button type="button" id="support-link">Chat with us</button>

<script>
  document.getElementById("support-link").addEventListener("click", () => {
    window.__konvoai?.open();
  });
</script>

Hide the widget on specific pages

// e.g. hide it during checkout, show it everywhere else
if (location.pathname.startsWith("/checkout")) {
  window.__konvoai?.hide();
} else {
  window.__konvoai?.show();
}

Identify the visitor after login

If your app learns the visitor's email only after the widget has loaded — for example after an SPA sign-in completes — call identify() instead of relying on the global alone:

window.__konvoai?.identify(user.email);

The widget associates the conversation with that email as soon as auth is ready. You can call it before or after opening the panel.

window.__konvoai_widget_email — identifying the visitor

If your page already knows the signed-in visitor's email, set it on window.__konvoai_widget_email. The widget picks it up and associates the conversation with that person, so they don't have to type their email into the chat.

<script>
  // Set this with whatever your app knows about the logged-in user.
  window.__konvoai_widget_email = "ada@example.com";
</script>

• Set it before or while the widget is open — in automatic collection mode the widget re-reads it for up to about ten seconds after the panel opens, so a value set shortly after open (e.g. when your auth callback runs) is still picked up. For values that may arrive later, prefer identify().
• Only a well-formed email address is accepted; anything else is ignored.
• This is most useful when the channel's email collection is set to automatic in the dashboard: the widget uses the value you provide instead of prompting the visitor. On some commerce platforms the widget can also detect the logged-in customer automatically, but setting the global is the reliable, framework-agnostic way to do it.