# Configuration

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

Product: Clad Widget SDK
Source: https://docs.useclad.ai/widget/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. Set `false` to mount it yourself with [`render()`](#render-modes). |
| `locale` | `string` | workspace default | BCP‑47 locale, e.g. `"en-US"`. |
| `theme` | `ThemeConfig` | workspace default | Initial theme overrides. See [Theming](#theming-locale--z-index). |
| `launcher` | `LauncherConfig` | workspace default | Launcher position/label/badge/icon. |
| `content` | `ContentConfig` | built‑in defaults | Header title + home greeting/subtitle copy. See [Header & branding](#header--branding). |
| `privacy` | `PrivacyConfig` | `{}` | Initial cookie‑consent level. |
| `features` | `FeatureOverrides` | workspace default | Show/hide in‑iframe surfaces from code. See below. |
| `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()`).

### Feature visibility overrides (`features`)

Each widget has server‑side feature flags (managed under **Settings →
Integrations → Web Widget**, or via the admin API). The `features` option lets
you override those **from your install code** for a given page/app — so you can
toggle surfaces without round‑tripping through the dashboard:

```js
window.SupportChatSettings = {
  workspaceId: "{YOUR_WORKSPACE_ID}",
  widgetId: "{YOUR_WIDGET_ID}",
  features: {
    knowledgeBase: false,  // hide the "Find an answer" search
    ticketForms: true,     // show the "Quick requests" form cards
    conversations: true,   // show the message entry point + recent list
  },
};
```

| Key | Surface |
|---|---|
| `conversations` | "Send us a message" entry point + the conversation list (live chat + past conversations). |
| `knowledgeBase` | Knowledge base search on the home screen. |
| `ticketForms` | "Quick requests" ticket‑form cards on the home screen. |
| `aiAnswers` | AI answers / deflection (turns KB search into the [AI assistant chat](#ai-assistant-chat)). |
| `customLauncher` | Use a custom launcher in place of the default bubble. |

Semantics: a value of `false` **always hides** the surface; a value of `true`
shows it, but the data behind it stays gated server‑side, so a force‑enabled
surface only appears when the feature is also enabled on the widget config (e.g.
ticket forms must exist and be enabled to show). Leave a key unset to inherit the
dashboard setting. These are also accepted on `SupportChat.createChat({ features })`.