Web SDK - Sagepilot Docs

The Web SDK is the script that powers the Sagepilot Website Widget. It loads the Sagepilot-hosted chat on your site and exposes a small JavaScript API on window.ChatWidget, so your own buttons, links, and flows can open the chat, identify signed-in customers, and send messages. There is no package to install. The SDK is a single script served by Sagepilot.

Requirements

A Website Widget channel in Sagepilot. See Website Widget to create one.
The channel’s widget key, in the format workspace_id:channel_id. You can copy it from the channel’s install script.
Access to your site’s HTML, theme files, or tag manager.

Quick start

Add the script

Paste this before the closing </body> tag on every page where chat should be available. It loads the widget and stores a promise, window.sagepilotWidgetReady, that resolves when the widget is ready.

<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"
      }).then(resolve, reject);
    };
    script.onerror = function () {
      reject(new Error("Sagepilot widget failed to load"));
    };
    document.head.appendChild(script);
  });
</script>

Open chat from your own button

<button type="button" data-sagepilot-open>Chat with us</button>

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

Identify signed-in customers

await window.sagepilotWidgetReady;
await window.ChatWidget.identify({
  user_id: "user_123",
  email: "[email protected]",
  name: "Jane Doe",
  user_hash: "HASH_FROM_YOUR_SERVER"
});

Replace WORKSPACE_ID:CHANNEL_ID with your widget key.

Start here

Install the widget

Add the script to a website, single-page app, tag manager, or Shopify store.

Configure the widget

Set launcher, placement, and layout options when the widget starts.

Open chat from your button

Connect chat to your own buttons, links, and banners.

Identify customers

Link chats to signed-in customers and verify their identity.

Draft and send messages

Prefill or send a message from your page.

API reference

Every window.ChatWidget method and what it returns.

How it works

The script adds a launcher button and a hidden chat frame to your page. The chat itself is hosted by Sagepilot, so appearance, greetings, conversation starters, and the AI agent come from the channel settings in Sagepilot. You can change those settings without editing your site.

Where you change it	What it controls
Sagepilot channel settings	Colors, logo, launcher position and text, welcome popup, conversation starters, contact form, OTP, identity verification, AI agent, and routing.
`ChatWidget.init()` options	Page-level overrides such as hiding the launcher, bottom padding, and stacking order. See Configuration.
`window.ChatWidget` methods	Runtime behavior from your code: opening and closing chat, identity, and messages.

On screens 768 px wide or narrower, the open chat fills the screen. On wider screens, it opens as a panel of up to 420 × 700 px on the side set in the channel settings.

​Requirements

​Quick start

​Start here