Open chat from your own button

Any element on your site can open the chat, for example a Chat with us link in your header, an Ask an expert button on product pages, or a help prompt inside a cart drawer.

Open chat from a button

This example assumes you installed the widget with the snippet in Installation, which creates window.sagepilotWidgetReady.

Mark the elements that open chat

Add the data-sagepilot-open attribute to any button or link. You can use it on as many elements as you like.

<button type="button" data-sagepilot-open>Chat with us</button>
<a href="#" data-sagepilot-open>Need help choosing a size?</a>

Handle the click

Add this once per page, after the widget snippet.

<script>
  document.addEventListener("click", async function (event) {
    if (!event.target.closest("[data-sagepilot-open]")) return;
    event.preventDefault();
    await window.sagepilotWidgetReady;
    window.ChatWidget.open();
  });
</script>

The handler listens on the whole page, so it also works for elements your theme or apps add later, such as a slide-out cart or a popup. If a visitor clicks before the widget has finished loading, the chat opens as soon as it is ready.

Hide the floating launcher

If only your own buttons should open the chat, add hideNativeLauncherButton: true to the init() call. This hides the launcher in the corner of the page and its welcome popup. ChatWidget.open() still works.

window.ChatWidget.init({
  host: "https://app.sagepilot.ai",
  key: "WORKSPACE_ID:CHANNEL_ID",
  hideNativeLauncherButton: true
});

The unread-message badge appears only on the Sagepilot launcher. If you hide it, visitors see new replies when they open the chat.

If you cannot change the install snippet

Use this version if the widget is already installed and you cannot edit its snippet, for example when it was installed with the Sagepilot Shopify app embed, through a tag manager, or with the one-line script from Embed Code. It does not need window.sagepilotWidgetReady.

<script>
  function openSagepilotChat() {
    var attempts = 0;
    (function tryOpen() {
      if (window.ChatWidget && window.ChatWidget.open()) return;
      if (++attempts < 40) setTimeout(tryOpen, 250);
    })();
  }

  document.addEventListener("click", function (event) {
    if (!event.target.closest("[data-sagepilot-open]")) return;
    event.preventDefault();
    openSagepilotChat();
  });
</script>

ChatWidget.open() returns false until the widget is ready, so the helper retries every 250 ms for up to 10 seconds. While it retries, the browser console may show [ChatWidget] Widget not initialized warnings. These are expected. Do not add a second copy of the widget script to reach the API. The widget must be loaded only once per page.

Complete example

A Shopify theme that shows its own Ask the concierge button and no floating launcher. Add this to layout/theme.liquid before </body>, and put the button wherever it should appear in your theme.

<button type="button" class="concierge-button" data-sagepilot-open>
  Ask the concierge
</button>

<script>
  window.sagepilotWidgetReady = new Promise(function (resolve, reject) {
    var script = document.createElement("script");
    script.src = "https://app.sagepilot.ai/chat-widget.js";
    script.async = true;
    script.onload = function () {
      window.ChatWidget.init({
        host: "https://app.sagepilot.ai",
        key: "WORKSPACE_ID:CHANNEL_ID",
        hideNativeLauncherButton: true
      }).then(resolve, reject);
    };
    script.onerror = function () {
      reject(new Error("Sagepilot widget failed to load"));
    };
    document.head.appendChild(script);
  });

  document.addEventListener("click", async function (event) {
    if (!event.target.closest("[data-sagepilot-open]")) return;
    event.preventDefault();
    await window.sagepilotWidgetReady;
    window.ChatWidget.open();
  });
</script>

Close and toggle the chat

Call	What it does
`window.ChatWidget.open()`	Opens the chat. Returns `true`, or `false` if the widget is not ready.
`window.ChatWidget.close()`	Closes the chat. Returns `true`, or `false` if the widget is not ready.
`window.ChatWidget.toggle()`	Opens the chat if it is closed and closes it if it is open. Returns `true` when it opened the chat and `false` when it closed it.
`window.ChatWidget.isOpen()`	Returns `true` if the chat is open.

For example, a button that switches between open and closed:

document.getElementById("help-toggle").addEventListener("click", async function () {
  await window.sagepilotWidgetReady;
  window.ChatWidget.toggle();
});

How opening behaves

open() always opens the full chat. It skips the welcome popup and the two-step intro card.
Calling open() while the chat is already open does nothing. Repeated clicks do not create extra windows or new conversations.
Opening the chat does not send a message. To prefill or send one, see Draft and send messages.
Visitors who have chatted before on the same browser see their existing conversations.
On screens 768 px wide or narrower, the chat opens full screen. Visitors close it with the close button inside the chat.

Verify the setup

Open your site in a private browser window.
Click your button. The chat should open.
Click it again several times. The same chat should stay open.
Close the chat and click the button again. It should reopen.
Repeat on a phone, or with your browser’s device toolbar set to a phone width.
In your browser’s developer tools, throttle the network to a slow connection, reload, and click the button immediately. The chat should open once the widget finishes loading.

If nothing happens, see Troubleshooting.

​Open chat from a button

​Hide the floating launcher

​If you cannot change the install snippet

​Complete example

​Close and toggle the chat

​How opening behaves

​Verify the setup

Open chat from a button

Hide the floating launcher

If you cannot change the install snippet

Complete example

Close and toggle the chat

How opening behaves

Verify the setup