> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagepilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK

> Add Sagepilot chat to any website and control it from your own code with the Web SDK.

The Web SDK is the script that powers the Sagepilot [Website Widget](/integrations/channels/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](/integrations/channels/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

<Steps>
  <Step title="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.

    ```html theme={null}
    <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>
    ```
  </Step>

  <Step title="Open chat from your own button">
    ```html theme={null}
    <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>
    ```
  </Step>

  <Step title="Identify signed-in customers">
    ```js theme={null}
    await window.sagepilotWidgetReady;
    await window.ChatWidget.identify({
      user_id: "user_123",
      email: "jane@example.com",
      name: "Jane Doe",
      user_hash: "HASH_FROM_YOUR_SERVER"
    });
    ```
  </Step>
</Steps>

Replace `WORKSPACE_ID:CHANNEL_ID` with your widget key.

## Start here

<CardGroup cols={3}>
  <Card title="Install the widget" icon="download" href="/sdks/web/installation">
    Add the script to a website, single-page app, tag manager, or Shopify store.
  </Card>

  <Card title="Configure the widget" icon="settings" href="/sdks/web/configuration">
    Set launcher, placement, and layout options when the widget starts.
  </Card>

  <Card title="Open chat from your button" icon="mouse-pointer-click" href="/sdks/web/opening-chat">
    Connect chat to your own buttons, links, and banners.
  </Card>

  <Card title="Identify customers" icon="user-check" href="/sdks/web/identity">
    Link chats to signed-in customers and verify their identity.
  </Card>

  <Card title="Draft and send messages" icon="send" href="/sdks/web/sending-messages">
    Prefill or send a message from your page.
  </Card>

  <Card title="API reference" icon="square-terminal" href="/sdks/web/api-reference">
    Every `window.ChatWidget` method and what it returns.
  </Card>
</CardGroup>

## 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](/sdks/web/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.