# Clad Support Chat — Full Documentation

> Documentation for Clad Support Chat — native, in-app support for your web app. Embed a chat widget with knowledge base, AI answers, and live conversations with your team.

Source: https://docs.useclad.ai

---

# Vibe Start

> Steps for vibe coders: let your AI agent set up the widget.

URL: https://docs.useclad.ai/vibe-start

Steps for vibe coders: grab your two IDs, then paste the prompt below into your
AI coding agent (Cursor, Claude Code, etc.) and let it add the widget for you.

### Step 1 — Find your Workspace ID and Widget ID

1. Sign in to your Clad dashboard at **[app.useclad.ai](https://app.useclad.ai)**.
2. Open **Settings → Integrations → Web Widget**.
3. Copy your **Workspace ID** (starts with `ws_`) and **Widget ID** (starts with
   `wgt_`). You'll paste these into the prompt in Step 2.

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">Where to find your IDs</p>
  <p class="img-ph__desc"><strong>Settings → Integrations → Web Widget</strong> in the Clad dashboard, with the Workspace ID and Widget ID clearly visible. Feel free to blur the real values — this just needs to show <em>where</em> the IDs live and what they look like.</p>
</div>

### Step 2 — Paste this prompt into your agent

Replace `{YOUR_WORKSPACE_ID}` and `{YOUR_WIDGET_ID}` with the IDs from Step 1, then paste the entire
prompt into your coding agent and let it run:

```text
You are adding the Clad Support Chat widget to this web application.

First, read the official documentation (fetch these URLs before writing code):
- Docs index:  https://docs.useclad.ai/llms.txt
- Full docs:   https://docs.useclad.ai/llms-full.txt
- Quickstart:  https://docs.useclad.ai/quickstart.md
Every page is available as Markdown by appending .md to its URL
(for example https://docs.useclad.ai/installation.md).

My credentials:
- Workspace ID: {YOUR_WORKSPACE_ID}
- Widget ID:    {YOUR_WIDGET_ID}

Then implement the integration:
1. Detect this project's framework (plain HTML, React, Next.js, Vue, etc.).
2. Install the widget using the single <script> snippet from the Quickstart.
   Do NOT use npm or any package manager — there is no package. The script
   loads from https://clad-server-staging.up.railway.app/widget/v1/widget.js.
   Add it once in the app shell so it runs
   on every page (e.g. index.html just before </body>, the Next.js root layout
   via next/script, or your framework's equivalent).
3. Set window.SupportChatSettings with my Workspace ID and Widget ID.
4. If this app has logged-in users, also set up identity verification:
   - Add a backend endpoint that returns a short-lived (<= 15 min) HS256 JWT,
     signed with a SUPPORT_CHAT_WIDGET_SECRET environment variable, including
     the claims described on the Identity verification page (sub, email, name,
     workspace_id, widget_id, exp).
   - Wire the SDK's tokenProvider to that endpoint, call identify() on login,
     and shutdown({ clearStorage: true }) on logout. Use the framework recipe
     that matches this codebase.
5. Follow the Security best practices page: never expose the widget secret in
   frontend code, keep tokens short-lived, and remind me to add my site's
   origin to the widget's allowed origins.
6. Do not hardcode secrets; read them from environment variables.
7. When done, summarize the files you changed and tell me exactly how to test
   that the launcher appears and that a test message reaches the support inbox.

Keep the integration minimal and idiomatic for this codebase.
```

The prompt points your agent at these machine‑readable resources, which it
fetches before writing any code:

- **[`/llms.txt`](https://docs.useclad.ai/llms.txt)** — a concise index of every documentation page.
- **[`/llms-full.txt`](https://docs.useclad.ai/llms-full.txt)** — the entire documentation in a single file.
- **[`/quickstart.md`](https://docs.useclad.ai/quickstart.md)** — the copy‑paste install snippet.

> Any page on this site is available as raw Markdown — just append `.md` to its
> URL. Point your agent at the exact page it needs (for example
> `https://docs.useclad.ai/identity-verification.md`).

### Step 3 — Review the result

When the agent finishes, the launcher should appear on your site. Open it, send
a test message, and confirm it lands in your support inbox.

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">The widget launcher on a live site</p>
  <p class="img-ph__desc">A screenshot of a web app with the Support Chat <strong>launcher button</strong> visible in the corner (ideally on a real-looking product page, not a blank page), to show the end result of the integration.</p>
</div>

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">An open conversation</p>
  <p class="img-ph__desc">A screenshot of the <strong>messenger panel open</strong> with a sample conversation — a visitor message and an agent reply — so readers can see what their users will experience.</p>
</div>

If something looks off, check the [Troubleshooting & FAQ](#troubleshooting--faq)
page — or hand that page to your agent (append `.md`) and ask it to fix the issue.

---

# How it works

> Architecture overview: how the SDK, hosted widget iframe, and Widget API fit together.

URL: https://docs.useclad.ai/how-it-works

Support Chat has three moving parts that work together:

1. **The SDK on your page.** You add a single `<script>` tag (see
   [Quickstart](#quickstart)) — there's nothing to bundle or install. The SDK
   exposes a typed, Promise‑based API and owns *identity* and *lifecycle*: who
   the current user is, and when the messenger boots, updates, or shuts down.

2. **The hosted widget UI.** The chat interface itself renders inside a
   **hosted iframe** served by Clad — not on your page. The SDK communicates
   with it over `postMessage`. Because the UI lives in an isolated iframe, your
   CSS can never collide with it and your page never gains access to the session
   token; the iframe acts as a security boundary.

3. **The Widget API and your support platform.** The widget talks to Clad's
   backend over HTTPS, plus a WebSocket for realtime updates. Messages a visitor
   sends become real conversations in your support inbox, and replies from your
   agents (or AI) stream back into the widget in real time.

In short: the SDK lives on your site and controls identity, the hosted iframe
renders the conversation, and Clad's backend routes everything into your
support platform — tickets, agents, and knowledge base.

You configure each widget once in your **workspace admin** (theme, launcher,
allowed origins, knowledge base, forms, identity rules) and reference it from
your code with a `workspaceId` and `widgetId`.

---

# Quickstart

> Add the widget with one script tag and start chatting in minutes.

URL: https://docs.useclad.ai/quickstart

Paste this snippet just before `</body>`. It boots an **anonymous** session
automatically — visitors can start chatting immediately.

```html
<script>
  window.SupportChatSettings = {
    workspaceId: "{YOUR_WORKSPACE_ID}",
    widgetId: "{YOUR_WIDGET_ID}",
    region: "us",
  };
  (function (w, d) {
    w.SupportChat = w.SupportChat || function () {
      (w.SupportChat.q = w.SupportChat.q || []).push(arguments);
    };
    var s = d.createElement("script");
    s.async = true;
    s.src = "https://clad-server-staging.up.railway.app/widget/v1/widget.js";
    d.head.appendChild(s);
  })(window, document);
</script>
```

> Find your `workspaceId` and `widgetId` in **Settings → Integrations → Web
> Widget**.

That's it — a launcher appears in the corner. To identify logged‑in users and
unlock per‑user history, continue to [Identity verification](#identity-verification-jwt).

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">The launcher after install</p>
  <p class="img-ph__desc">A web page with the Support Chat <strong>launcher button</strong> in the bottom corner, right after adding the snippet — to show the immediate result of the Quickstart.</p>
</div>

---

# Installation

> Add Support Chat with a single script tag. Configure regions and self-hosting.

URL: https://docs.useclad.ai/installation

Support Chat installs with a single `<script>` tag — there's no package to add
and no build step. Drop the [Quickstart](#quickstart) snippet in just before your
closing `</body>` tag and you're done.

### Using the widget

After the script loads, the booted, typed instance is available as
`window.supportChat`. A legacy string API is also supported for quick,
imperative calls:

```js
SupportChat("open");
SupportChat("on", "unread:change", ({ payload }) => console.log(payload.count));
```

Commands invoked before the script finishes loading are queued and replayed once
it's ready, so it's safe to call the API at any time.

For full programmatic control — for example in a single‑page app where you want
to hold a reference to the instance — the loader also exposes a factory on the
global once it has loaded:

```js
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
});

await chat.boot();
```

> Throughout these docs, `chat` refers to your Support Chat instance — either
> `window.supportChat` (created automatically from your settings) or one you
> create yourself with `SupportChat.createChat(...)`.

### Regions & self‑hosting

`region` selects the data‑residency endpoints. It defaults to `us`. Set it in
`window.SupportChatSettings` (or pass it to `SupportChat.createChat`).

| Region | Value |
|---|---|
| United States | `us` |
| European Union | `eu` |
| Australia | `au` |
| Custom / self‑hosted / staging | `custom` (also set `apiBase` + `widgetBase`) |

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  region: "custom",
  apiBase: "https://support-api.example.com",
  widgetBase: "https://support-widget.example.com/v1",
};
```

---

# Configuration

> Every widget configuration option — workspace, region, theming, launcher, and more.

URL: https://docs.useclad.ai/configuration

You configure a widget either by assigning `window.SupportChatSettings` before
the loader runs (the Quickstart snippet does exactly this) or by passing the same
options to `SupportChat.createChat(...)`:

```js
// Option 1 — set settings, let the loader auto‑boot:
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
};

// Option 2 — create an instance programmatically:
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
});
```

| Option | Type | Default | Description |
|---|---|---|---|
| `workspaceId` | `string` | — | **Required.** Your workspace id (`ws_…`). |
| `widgetId` | `string` | — | Widget id (`wgt_…`). Optional only if the workspace has a default widget. |
| `region` | `"us" \| "eu" \| "au" \| "custom"` | `"us"` | Data‑residency endpoints. |
| `apiBase` | `string` | region default | API base URL (for `custom`/self‑host). |
| `widgetBase` | `string` | region default | Hosted widget UI base URL. |
| `autoBoot` | `boolean` | `true` | Auto‑boot an anonymous session on load. |
| `autorender` | `boolean` | `true` | Mount the floating widget automatically. |
| `locale` | `string` | workspace default | BCP‑47 locale, e.g. `"en-US"`. |
| `theme` | `ThemeConfig` | workspace default | Initial theme overrides. |
| `launcher` | `LauncherConfig` | workspace default | Launcher position/label/badge. |
| `privacy` | `PrivacyConfig` | `{}` | Initial cookie‑consent level. |
| `debug` | `boolean` | `false` | Verbose console diagnostics. |

These options are read once when the session is created; network work happens on
[`boot()`](#the-session-lifecycle). Ongoing changes are made with the runtime
methods documented below (for example [`update()`](#the-session-lifecycle) and
`setTheme()`).

---

# The session lifecycle

> boot, identify, update, shutdown, and destroy — the full lifecycle of a chat session.

URL: https://docs.useclad.ai/session-lifecycle

A Support Chat session moves through a predictable set of phases. After the
script loads, it goes from **`not_initialized`** to **`loading`** and then
**`ready`**. Calling [`boot()`](#bootoptions) transitions it through
**`booting`** into either an **`anonymous`** or an **`authenticated`** session,
depending on whether you supplied a user.

Once live, the realtime connection may move between **`reconnecting`** and
**`disconnected`** as network conditions change — this is handled for you
automatically. Calling [`shutdown()`](#shutdownoptions) ends the session
(**`shutdown`**), and [`destroy()`](#destroy) tears the widget down entirely
(**`destroyed`**).

You can read the current phase at any time via `chat.state`.

### `boot(options?)`

Creates or resumes a session. With no `user`, the session is **anonymous**.
With a `user`, you should supply a `tokenProvider` (see
[Identity verification](#identity-verification-jwt)).

```ts
await chat.boot({
  user: {
    id: currentUser.id,
    email: currentUser.email,
    name: currentUser.name,
  },
  company: {
    id: currentOrg.id,
    name: currentOrg.name,
    plan: currentOrg.plan,
  },
  tokenProvider: () =>
    fetch("/api/support-chat-token").then((r) => r.text()),
});
```

- Idempotent for the same identity.
- Calling `boot()` with a **different** identified user throws — call
  [`shutdown()`](#shutdownoptions) first, or use [`identify()`](#identifyoptions).

### `identify(options)`

Upgrades an anonymous session to an authenticated user (and merges anonymous
history when possible). See [Anonymous → authenticated upgrade](#anonymous--authenticated-upgrade).

### `update(options)`

Refreshes user/company traits and ephemeral page context. Safe to call on SPA
route changes; it never creates duplicate users and is rate‑limited.

```ts
await chat.update({
  user: { id: "user_123", traits: { role: "admin" } },
  company: { id: "org_456", plan: "enterprise" },
  context: { currentPage: "billing", accountHealth: "red" },
});
```

### `shutdown(options?)`

Call on **logout**. Clears user‑specific state and closes the realtime
connection. Pass `{ clearStorage: true }` to also remove anonymous/session
identifiers — important on shared computers so a previous user's conversations
don't linger.

```ts
await chat.shutdown({ clearStorage: true });
```

### `destroy()`

Removes the iframe, listeners, and timers. Persistent storage is left intact
unless you previously called `shutdown({ clearStorage: true })`.

```ts
await chat.destroy();
```

---

# Identity verification (JWT)

> Securely identify logged-in users with short-lived, server-signed JWTs. Includes backend recipes.

URL: https://docs.useclad.ai/identity-verification

Authenticated users must be verified with a **short‑lived JWT minted by your
backend** — never put secrets in the browser. The SDK calls your
`tokenProvider` on boot, before expiry, and after a `401`.

### 1. Get your widget's signing secret

In **Settings → Integrations → Web Widget**, copy the **JWT secret**. Store it
as a backend environment variable (e.g. `SUPPORT_CHAT_WIDGET_SECRET`). Treat it
like a password; rotate it from the same screen if leaked.

### 2. Expose a token endpoint on your backend

The endpoint returns a signed JWT (HS256) for the currently logged‑in user.

**Required claims:** `sub` (your stable user id), `widget_id`, `workspace_id`,
and `exp`. Recommended: `email`, `name`, `company_id`, `jti`.

```jsonc
{
  "iss": "your_backend",
  "aud": "clad_support_chat",
  "sub": "user_123",
  "email": "rachel@example.com",
  "name": "Rachel",
  "company_id": "org_456",
  "workspace_id": "{YOUR_WORKSPACE_ID}",
  "widget_id": "{YOUR_WIDGET_ID}",
  "iat": 1760000000,
  "exp": 1760000900,
  "jti": "a-unique-token-id"
}
```

<details>
<summary><b>Node.js (Express)</b></summary>

```ts
import jwt from "jsonwebtoken";

app.get("/api/support-chat-token", requireLogin, (req, res) => {
  const token = jwt.sign(
    {
      sub: req.user.id,
      email: req.user.email,
      name: req.user.name,
      company_id: req.user.orgId,
      workspace_id: "{YOUR_WORKSPACE_ID}",
      widget_id: "{YOUR_WIDGET_ID}",
    },
    process.env.SUPPORT_CHAT_WIDGET_SECRET,
    { expiresIn: "15m", audience: "clad_support_chat" }
  );
  res.type("text/plain").send(token);
});
```
</details>

<details>
<summary><b>Python (Flask)</b></summary>

```python
import jwt, time, os
from flask import Response

@app.get("/api/support-chat-token")
@login_required
def support_chat_token():
    now = int(time.time())
    token = jwt.encode({
        "sub": current_user.id,
        "email": current_user.email,
        "name": current_user.name,
        "company_id": current_user.org_id,
        "workspace_id": "{YOUR_WORKSPACE_ID}",
        "widget_id": "{YOUR_WIDGET_ID}",
        "iat": now, "exp": now + 900,
        "aud": "clad_support_chat",
    }, os.environ["SUPPORT_CHAT_WIDGET_SECRET"], algorithm="HS256")
    return Response(token, mimetype="text/plain")
```
</details>

<details>
<summary><b>Ruby (Rails)</b></summary>

```ruby
def support_chat_token
  payload = {
    sub: current_user.id, email: current_user.email, name: current_user.name,
    company_id: current_user.org_id, workspace_id: "{YOUR_WORKSPACE_ID}", widget_id: "{YOUR_WIDGET_ID}",
    iat: Time.now.to_i, exp: 15.minutes.from_now.to_i, aud: "clad_support_chat"
  }
  render plain: JWT.encode(payload, ENV["SUPPORT_CHAT_WIDGET_SECRET"], "HS256")
end
```
</details>

<details>
<summary><b>Go</b></summary>

```go
claims := jwt.MapClaims{
    "sub": user.ID, "email": user.Email, "name": user.Name,
    "company_id": user.OrgID, "workspace_id": "{YOUR_WORKSPACE_ID}", "widget_id": "{YOUR_WIDGET_ID}",
    "iat": time.Now().Unix(), "exp": time.Now().Add(15 * time.Minute).Unix(),
    "aud": "clad_support_chat",
}
tok, _ := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).
    SignedString([]byte(os.Getenv("SUPPORT_CHAT_WIDGET_SECRET")))
w.Write([]byte(tok))
```
</details>

### 3. Wire it into the SDK

```ts
await chat.boot({
  user: { id: user.id, email: user.email, name: user.name },
  tokenProvider: () => fetch("/api/support-chat-token").then((r) => r.text()),
});
```

### Token lifecycle

- The SDK requests a token on boot, refreshes it **before** expiry, and again
  after any `401`.
- Keep tokens short‑lived (≤ 15 minutes). The widget handles refresh
  transparently; expiry surfaces as an [`auth:expired`](#events) event.
- The platform verifies signature, expiration, audience, and that
  `workspace_id` / `widget_id` match the widget — and that the request origin
  is allow‑listed.

---

# Anonymous → authenticated

> Upgrade an anonymous session to an identified user and merge conversation history.

URL: https://docs.useclad.ai/identify-upgrade

If a visitor chats anonymously and later logs in, call `identify()` to upgrade
the session in place. Anonymous conversation history is merged into the
identified user when safe; if the user already had conversations, those appear
after the upgrade.

```ts
await chat.identify({
  user: { id: "user_123", email: "rachel@example.com", name: "Rachel" },
  company: { id: "org_456", name: "Acme Inc" },
  tokenProvider: fetchSupportChatToken,
});
```

---

# Visibility & launchers

> Open, close, show, and hide the messenger — or wire up your own custom launcher button.

URL: https://docs.useclad.ai/visibility-launchers

All visibility methods are safe to call before or after boot; calls made before
the widget is ready are queued.

```ts
await chat.open();   // open the messenger panel
await chat.close();  // close the panel (launcher stays visible)

chat.show();         // show all widget surfaces
chat.hide();         // hide all widget surfaces

chat.showLauncher();
chat.hideLauncher();
chat.setLauncherVisible(false);
```

### Custom launcher

Hide the built‑in launcher and trigger the widget from your own button. Unread
counts are still delivered via events.

```ts
const chat = SupportChat.createChat({
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  launcher: { showUnreadBadge: false },
});

chat.hideLauncher();

document.querySelector("#support-button")
  ?.addEventListener("click", () => chat.open());

const off = chat.on("unread:change", ({ payload }) => {
  document.querySelector("#support-badge")!.textContent = String(payload.count);
});
```

---

# Render modes

> Floating, embedded, and custom-launcher render modes for the chat widget.

URL: https://docs.useclad.ai/render-modes

```ts
await chat.render({ mode: "floating" });                         // default

await chat.render({ mode: "embedded", target: "#support-panel" }); // inline

await chat.render({ mode: "custom-launcher", launcher: false });   // your launcher
```

| Mode | Behavior |
|---|---|
| `floating` | Default. Floating launcher + panel anchored to a corner. |
| `embedded` | Renders the widget inside a container you provide (`target`). |
| `custom-launcher` | Hides our launcher; you control open/close. Events still fire. |

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">Floating vs. embedded</p>
  <p class="img-ph__desc">A side‑by‑side (or two stacked shots) showing the <strong>floating</strong> widget anchored to a corner and the <strong>embedded</strong> widget rendered inline inside a page container, so readers can see the difference between render modes.</p>
</div>

---

# Theming, locale & z-index

> Match the widget to your brand with theme colors, fonts, locale, and z-index control.

URL: https://docs.useclad.ai/theming

```ts
chat.setTheme({
  mode: "system",                // "light" | "dark" | "system"
  colors: {
    primary: "#4f46e5",
    background: "#ffffff",
    surface: "#f8fafc",
    text: "#0f172a",
    mutedText: "#64748b",
    userMessage: "#4f46e5",
    agentMessage: "#f1f5f9",
    danger: "#dc2626",
  },
  borderRadius: "lg",            // none | sm | md | lg | xl | <css length>
  fontFamily: "Inter, system-ui, sans-serif",
});

chat.setLocale("en-US");
chat.setZIndex(999999);
```

You can also set defaults in `window.SupportChatSettings` (or
`SupportChat.createChat`), or in your workspace admin.

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">A themed widget</p>
  <p class="img-ph__desc">The widget styled to match a brand — custom primary color, font, and rounded corners — ideally next to the default look, to show what theming achieves.</p>
</div>

---

# Conversations

> Start, list, show, and send messages in conversations with idempotent retries.

URL: https://docs.useclad.ai/conversations

### Start a conversation

```ts
const conversation = await chat.startConversation({
  subject: "Billing issue",
  message: "I need help understanding this invoice.",
  tags: ["billing", "high-value-account"],
  customFields: { plan: "enterprise", mrr: 25000 },
  metadata: { invoiceId: "inv_123", source: "billing_page" },
});
```

If `message` is omitted, the composer opens for the user to type. `tags` and
`customFields` map to your platform's tags/fields where configured.

### List, show, send, mark read

```ts
const page = await chat.listConversations({ limit: 20 });      // Page<Conversation>
await chat.showConversation(conversation.id);

const message = await chat.sendMessage({
  conversationId: conversation.id,
  text: "Here is more context.",
  clientMessageId: crypto.randomUUID(),   // optional, for idempotent retries
});

await chat.markConversationRead(conversation.id);
```

- `listConversations` returns only the current user's conversations (anonymous
  users see only their browser session's conversations).
- `clientMessageId` makes retries idempotent — the same id never creates a
  duplicate message.

### Prefill a new message

```ts
await chat.showNewMessage({
  prefill: "I ran into an error while upgrading my plan.",
  metadata: { source: "upgrade_error_modal" },
});
```

Opens the composer pre‑filled (it does **not** send automatically).

---

# Knowledge base & forms

> Let users search your knowledge base and submit ticket forms without leaving your app.

URL: https://docs.useclad.ai/knowledge-base-forms

```ts
const articles = await chat.searchArticles("how do I update billing");
await chat.showArticle(articles[0].id);

await chat.showTicketForm("contact", {
  prefill: { summary: "Cannot log in", severity: "high" },
});
```

- `searchArticles` returns only **published**, end‑user‑visible articles.
- Submitting a ticket form creates a conversation in your inbox and emits
  [`form:submitted`](#events). Unknown prefill fields are ignored.

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">Knowledge base in the widget</p>
  <p class="img-ph__desc">The widget showing <strong>knowledge base search results</strong> (and/or an open article), so users can see they can self‑serve answers without leaving your app.</p>
</div>

<div class="img-ph">
  <span class="img-ph__badge">📷 Screenshot needed</span>
  <p class="img-ph__title">A ticket form in the widget</p>
  <p class="img-ph__desc">The widget showing an <strong>embedded ticket form</strong> with a couple of fields, to illustrate submitting an async request from inside the messenger.</p>
</div>

---

# Context, tags & custom fields

> Attach page context, tags, and custom fields to conversations.

URL: https://docs.useclad.ai/context-tags-fields

```ts
chat.setContext({ page: "billing", url: location.href, accountHealth: "red" });
chat.setConversationTags(["billing", "enterprise"]);
chat.setCustomFields({ plan: "enterprise", mrr: 25000, onboarding_complete: true });
```

- **Context** is ephemeral and attached to future conversations/messages.
- **Tags** and **custom fields** apply to new conversations (and future
  messages where supported); they are not retroactive.
- Custom‑field keys should be slugs; values should be JSON primitives.

> ⚠️ Never put passwords, secrets, full card numbers, access tokens, or other
> sensitive data in `metadata`/`customFields`.

---

# Privacy & cookie consent

> Control storage and analytics with granular cookie-consent levels.

URL: https://docs.useclad.ai/privacy-cookie-consent

```ts
await chat.setCookieConsent("functional"); // all | functional | essential | none
```

| Level | Behavior |
|---|---|
| `all` | Essential + functional + analytics storage allowed. |
| `functional` | Essential + functional; analytics disabled. |
| `essential` | Only strictly necessary storage. |
| `none` | Hides the widget, clears local/session storage, disables chat. |

For logout on shared devices, prefer `shutdown({ clearStorage: true })`.

---

# Events

> Subscribe to lifecycle, connection, conversation, and message events with on().

URL: https://docs.useclad.ai/events

Subscribe with `on()`, which returns an **unsubscribe** function. Every event
uses the same envelope.

```ts
const off = chat.on("message:received", (event) => {
  console.log(event.payload.conversation.id, event.payload.message.id);
});

off(); // stop listening
```

```ts
interface ChatEvent<TPayload> {
  id: string;
  type: ChatEventName;
  createdAt: string;   // ISO‑8601
  payload: TPayload;
}
```

### Event reference

| Event | Payload (key fields) | Fires when |
|---|---|---|
| `ready` | `{ identityType }` | The widget has booted and is ready. |
| `error` | `{ code, message }` | A recoverable/visible error occurred. |
| `open` / `close` | — | The messenger panel opened/closed. |
| `show` / `hide` | — | All surfaces shown/hidden. |
| `launcher:show` / `launcher:hide` | — | The launcher visibility changed. |
| `auth:expired` | — | The identity token expired (refresh underway). |
| `auth:changed` | `{ identityType }` | The user became identified. |
| `connection:state` | `{ state }` | `connecting` / `connected` / `reconnecting` / `disconnected`. |
| `unread:change` | `{ count }` | The total unread count changed. |
| `conversation:started` | `{ conversation }` | A conversation was created. |
| `conversation:opened` | `{ conversation }` | A conversation was opened in the UI. |
| `conversation:updated` | `{ conversation }` | Status/assignee/etc. changed. |
| `conversation:resolved` | `{ conversation }` | A conversation was resolved/closed. |
| `conversation:assigned` | `{ conversation }` | An agent/team was assigned. |
| `message:sending` | `{ conversation, message }` | An outbound message is being sent. |
| `message:sent` | `{ conversation, message }` | An outbound message was accepted. |
| `message:received` | `{ conversation, message }` | An agent/bot message arrived. |
| `message:failed` | `{ conversation, error }` | A message failed to send. |
| `message:read` | `{ conversation }` | A message was read. |
| `typing:start` / `typing:stop` | `{ conversationId }` | Typing indicator changed. |
| `article:opened` | `{ articleId }` | A KB article was opened. |
| `form:opened` | `{ formId }` | A ticket form was opened. |
| `form:submitted` | `{ formId, conversationId }` | A ticket form was submitted. |

---

# Error handling

> Handle SupportChatError, inspect error codes, and retry recoverable failures.

URL: https://docs.useclad.ai/error-handling

Async methods reject with a `SupportChatError`, exposed on the global as
`SupportChat.Error`:

```js
try {
  await chat.sendMessage({ conversationId, text });
} catch (err) {
  if (err instanceof SupportChat.Error) {
    console.error(err.code, err.message, err.requestId);
    if (err.recoverable) {
      // safe to retry (often after a short backoff)
    }
  }
}
```

| Field | Description |
|---|---|
| `code` | Machine‑readable error code (below). |
| `message` | Human‑readable description. |
| `reason` | Optional finer‑grained reason. |
| `requestId` | Correlation id — include it in support requests. |
| `recoverable` | Whether a retry may succeed. |

**Codes:** `not_ready`, `not_booted`, `auth_required`, `auth_expired`,
`invalid_token`, `invalid_origin`, `widget_disabled`, `rate_limited`,
`network_error`, `conversation_not_found`, `message_invalid`,
`message_send_failed`, `attachment_too_large`, `unsupported_file_type`,
`form_not_found`, `article_not_found`, `validation_error`, `internal_error`.

---

# Realtime behavior

> WebSocket transport, automatic reconnection, message de-duplication, and unread tracking.

URL: https://docs.useclad.ai/realtime

- **Transport:** WebSocket, established after boot. If WebSocket is unavailable,
  delivery automatically falls back so messages still arrive.
- **Reconnect:** automatic with exponential backoff. On reconnect, missed
  messages are replayed and de‑duplicated — you never see duplicates, and
  `clientMessageId` makes your own retries idempotent.
- **Unread:** the widget tracks unread counts across the user's conversations
  and emits `unread:change`, even while the panel is closed.
- **Connection state:** subscribe to `connection:state` to reflect
  online/offline status in your own UI if desired.

No infrastructure is required on your side — the realtime gateway is hosted.

---

# Framework recipes

> Copy-paste integration recipes for React, Next.js (App Router), and Vue 3.

URL: https://docs.useclad.ai/framework-recipes

### React

Include the [Quickstart](#quickstart) `<script>` snippet once in your app shell,
then use a small hook to identify the user on login and shut down on logout.
Calls made before the widget finishes loading are queued and replayed, so you
don't need to wait for it to be ready.

```jsx
import { useEffect } from "react";

export function useSupportChat(user) {
  useEffect(() => {
    if (user) {
      SupportChat("identify", {
        user,
        tokenProvider: () =>
          fetch("/api/support-chat-token").then((r) => r.text()),
      });
    } else {
      SupportChat("shutdown", { clearStorage: true });
    }
  }, [user?.id]);
}
```

### Next.js (App Router)

Load the widget with `next/script` and render it once in your root layout:

```jsx
"use client";
import Script from "next/script";

export default function SupportChatLoader() {
  return (
    <Script id="support-chat" strategy="afterInteractive">
      {`
        window.SupportChatSettings = { workspaceId: "{YOUR_WORKSPACE_ID}", widgetId: "{YOUR_WIDGET_ID}" };
        (function (w, d) {
          w.SupportChat = w.SupportChat || function () {
            (w.SupportChat.q = w.SupportChat.q || []).push(arguments);
          };
          var s = d.createElement("script");
          s.async = true;
          s.src = "https://clad-server-staging.up.railway.app/widget/v1/widget.js";
          d.head.appendChild(s);
        })(window, document);
      `}
    </Script>
  );
}
```

### Vue 3

With the [Quickstart](#quickstart) `<script>` snippet included once in your
`index.html`, drive the widget from your components:

```js
import { onMounted } from "vue";

export function useSupportChat(user) {
  onMounted(() => {
    if (user) {
      SupportChat("identify", {
        user,
        tokenProvider: () =>
          fetch("/api/support-chat-token").then((r) => r.text()),
      });
    }
  });
}
```

---

# Security best practices

> Identity verification, allowed origins, CSP, and data-handling guidance.

URL: https://docs.useclad.ai/security

- **Verify identity with server‑minted JWTs.** Never embed the widget secret in
  frontend code. Keep tokens short‑lived.
- **Configure allowed origins** for your widget. Session creation is rejected
  from any other origin.
- **Don't send sensitive data** in `metadata`/`customFields` (passwords,
  secrets, full card numbers, tokens, PII you don't need).
- **Always `shutdown({ clearStorage: true })` on logout**, especially for shared
  devices.
- The widget renders user/agent text as plain text and sanitizes article HTML;
  the UI runs in an isolated iframe as a security boundary.
- A reasonable **Content‑Security‑Policy** on your site can allow the widget
  explicitly, e.g. `script-src https://clad-server-staging.up.railway.app; frame-src https://clad-server-staging.up.railway.app; connect-src https://clad-server-staging.up.railway.app wss://clad-server-staging.up.railway.app`.

---

# Browser support & performance

> Supported browsers, lazy-loaded UI, and the single hosted script delivery.

URL: https://docs.useclad.ai/browser-support

- Modern evergreen browsers (Chrome, Edge, Firefox, Safari). **IE is not
  supported.** Mobile web works; native mobile SDKs are separate.
- The loader is `async` and small; the chat UI loads lazily in its iframe and
  does not block your page.
- The SDK is delivered as a single hosted script from Clad's CDN — there's
  nothing to bundle. TypeScript definitions are available for typed access to
  the global API.

---

# Public Widget API

> The underlying HTTP + WebSocket Widget API for advanced and self-hosted scenarios.

URL: https://docs.useclad.ai/widget-api-reference

> Most integrators use the SDK and never call these directly. They are
> documented for self‑hosted/advanced scenarios and debugging. Base path:
> `https://clad-server-staging.up.railway.app/widget/v1`.

| Method & path | Purpose |
|---|---|
| `GET /config?workspace_id=&widget_id=` | Public, end‑user‑safe widget config. |
| `POST /sessions/anonymous` | Create/resume an anonymous session. |
| `POST /sessions/identify` | Upgrade to an authenticated session (send the identity JWT; the anonymous session token authorizes the merge). |
| `POST /sessions/refresh` | Extend a session. |
| `POST /sessions/shutdown` | Revoke the current session (logout). |
| `POST /sessions/realtime-token` | Mint a short‑lived token for the realtime gateway. |
| `GET /conversations` | List the session's conversations (cursor paginated). |
| `POST /conversations` | Create a conversation (`subject`, `message`, `tags`, `customFields`, `metadata`). |
| `GET /conversations/{id}` | Fetch one conversation. |
| `POST /conversations/{id}/read` | Mark read. |
| `GET /conversations/{id}/messages` | List messages (cursor paginated). |
| `POST /conversations/{id}/messages` | Send a message (`text`, `clientMessageId`). |
| `GET /articles/search?q=` | Search published articles. |
| `GET /articles/{id}` | Fetch an article. |
| `POST /ai/answer` | AI answer / article suggestions for a question. |
| `GET /forms` · `GET /forms/{id}` | List/fetch ticket forms. |
| `POST /forms/{id}/submissions` | Submit a ticket form. |
| `POST /events` | Ingest client analytics/audit events. |
| `WS /realtime?session_token=` | Realtime gateway (WebSocket). |

**Auth:** all endpoints except `GET /config` and `POST /sessions/anonymous`
require `Authorization: Bearer <session token>`. Mutating endpoints validate the
request `Origin` against the widget's allow‑list. Errors use a consistent
envelope: `{ "error": { code, message, reason?, requestId?, recoverable } }`.

---

# Widget configuration

> The WidgetConfig schema: identity rules, routing, features, theme, and AI behavior.

URL: https://docs.useclad.ai/widget-configuration

Configure widgets in **Settings → Integrations → Web Widget** (or via the admin
API). A widget config looks like:

```ts
interface WidgetConfig {
  id: string;                 // wgt_…
  workspaceId: string;        // ws_…
  name: string;
  enabled: boolean;
  allowedOrigins: string[];   // e.g. ["https://app.customer.com", "https://*.customer.com"]

  identity: {
    anonymousAllowed: boolean;
    jwtRequiredForIdentifiedUsers: boolean;
    allowAnonymousToIdentifiedMerge: boolean;
  };

  routing: {
    defaultTeamId?: string;
    assignmentStrategy?: "platform_default" | "round_robin" | "least_busy";
  };

  features: {
    conversations: boolean;
    attachments: boolean;
    knowledgeBase: boolean;
    aiAnswers: boolean;
    ticketForms: boolean;
    customLauncher: boolean;
  };

  theme: ThemeConfig;
  launcher: LauncherConfig;
  forms: { visibleFormIds: string[] };
  knowledgeBase: { enabledCollectionIds?: string[] };
  ai: {
    enabled: boolean;
    mode: "answer_first" | "suggest_articles" | "human_first";
    escalationBehavior: "attach_context" | "summary_only" | "none";
  };
}
```

`allowedOrigins` supports exact origins and single‑level subdomain wildcards
(`https://*.customer.com`).

---

# Troubleshooting & FAQ

> Solutions to common issues: widget not appearing, invalid origins, auth errors, and more.

URL: https://docs.useclad.ai/troubleshooting

**The widget doesn't appear.**
Check the browser console for errors, confirm `workspaceId`/`widgetId`, and that
your page's origin is in the widget's **allowed origins**. The `GET /config`
call must succeed.

**`invalid_origin` when starting a session.**
Add your site's exact origin (scheme + host + port) to the widget's allowed
origins. Wildcards are single‑label (`https://*.customer.com` matches
`app.customer.com` but not `a.b.customer.com`).

**`auth_required` / `auth_expired` for logged‑in users.**
Ensure `tokenProvider` returns a valid JWT signed with the widget secret and
including `sub`, `widget_id`, `workspace_id`, and a future `exp`. The SDK
refreshes automatically; a thrown `tokenProvider` surfaces as `error`.

**Agent replies don't appear in real time.**
Confirm the page can reach the API over HTTPS **and** WebSocket
(`wss://`). Corporate proxies sometimes block WebSocket; the widget falls back
but with slightly higher latency.

**Conversations from before login disappeared.**
Use `identify()` (not a fresh `boot` with a new user) to merge anonymous
history. Ensure `allowAnonymousToIdentifiedMerge` is enabled.

**Multiple users on one browser see each other's chats.**
Call `shutdown({ clearStorage: true })` on logout.

**How do I theme it to match my brand?**
Set `theme` in `window.SupportChatSettings` (or `SupportChat.createChat`), call
`setTheme(...)` at runtime, or set defaults in the workspace admin.

---

# Versioning & support

> How the widget and API are versioned, what stays stable, and how to get support.

URL: https://docs.useclad.ai/versioning

- The hosted widget UI and API are versioned in the URL path (`/v1/`); breaking
  changes ship under a new version, so your existing `<script>` tag keeps
  working.
- The public SDK method names, the Promise‑based API, the event system, the
  identity/JWT model, and the hosted‑iframe default are stable contracts within
  a major version.
- Include the `requestId` from a `SupportChatError` when contacting support.

---

# TypeScript reference

> Key types and the full SupportChat interface available on the global API.

URL: https://docs.useclad.ai/typescript-reference

Type definitions for the global Support Chat API are available for TypeScript
projects. The members below live on the global `SupportChat` object once the
loader script has run. Key types:

```ts
// Exposed on the global, e.g. `SupportChat.createChat(...)`.
function createChat(options: CreateChatOptions): SupportChat;
const version: string;

// Exposed as `SupportChat.Error`.
class SupportChatError extends Error {
  code: SupportChatErrorCode;
  reason?: string;
  requestId?: string;
  recoverable: boolean;
}

interface SupportChat {
  boot(options?: BootOptions): Promise<void>;
  identify(options: IdentifyOptions): Promise<void>;
  update(options: UpdateOptions): Promise<void>;
  shutdown(options?: ShutdownOptions): Promise<void>;
  destroy(): Promise<void>;

  open(): Promise<void>;
  close(): Promise<void>;
  show(): void;
  hide(): void;
  showLauncher(): void;
  hideLauncher(): void;
  setLauncherVisible(visible: boolean): void;

  render(options: RenderOptions): Promise<void>;

  startConversation(options?: StartConversationOptions): Promise<Conversation>;
  showConversation(conversationId: string): Promise<void>;
  listConversations(options?: PaginationOptions): Promise<Page<Conversation>>;
  sendMessage(options: SendMessageOptions): Promise<Message>;
  markConversationRead(conversationId: string): Promise<void>;
  showNewMessage(options?: ShowNewMessageOptions): Promise<void>;

  searchArticles(query: string): Promise<Article[]>;
  showArticle(articleId: string): Promise<void>;
  showTicketForm(formId: string, options?: ShowTicketFormOptions): Promise<void>;

  setContext(context: Record<string, JsonValue>): void;
  setConversationTags(tags: string[]): void;
  setCustomFields(fields: Record<string, JsonValue>): void;

  setTheme(theme: ThemeConfig): void;
  setLocale(locale: string): void;
  setZIndex(zIndex: number): void;
  setCookieConsent(consent: CookieConsent): Promise<void>;

  on<E extends ChatEventName>(event: E, handler: ChatEventHandler<E>): () => void;
  off<E extends ChatEventName>(event: E, handler: ChatEventHandler<E>): void;

  readonly state: SdkState;
}
```

See the Support Chat `.d.ts` type definitions for the complete set
(`Conversation`, `Message`, `ThemeConfig`, `LauncherConfig`, event payload maps,
and more).

---