> ## 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.

# Configuration

> Options you can pass to ChatWidget.init() and how they combine with channel settings.

Most widget settings live on the channel in Sagepilot, so you can change them without editing your site. `ChatWidget.init()` accepts a few page-level options on top of those settings.

```js theme={null}
window.ChatWidget.init({
  host: "https://app.sagepilot.ai",
  key: "WORKSPACE_ID:CHANNEL_ID",
  hideNativeLauncherButton: true,
  bottomPadding: 24,
  closedZIndex: 990
});
```

Call `init()` once per page. It returns a promise that resolves when the widget is ready. See [Installation](/sdks/web/installation) for the recommended snippet.

## Options

| Option                     | Type      | Default                  | Description                                                                                                                                                                       |
| -------------------------- | --------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`                      | `string`  | Required                 | Widget key in the format `workspace_id:channel_id`.                                                                                                                               |
| `host`                     | `string`  | Required                 | Sagepilot host. Use `https://app.sagepilot.ai`, or `https://eu.sagepilot.ai` for workspaces hosted in the EU region.                                                              |
| `hideNativeLauncherButton` | `boolean` | `false`                  | Hides the floating launcher button and its welcome popup. Use this when only your own buttons should open the chat. See [Open chat from your own button](/sdks/web/opening-chat). |
| `bottomPadding`            | `number`  | Channel setting, or `20` | Distance in pixels between the bottom of the screen and the launcher and chat panel. Overrides the channel's bottom padding.                                                      |
| `closedZIndex`             | `number`  | `990`                    | Stacking order of the launcher while the chat is closed. Raise it if your site's elements cover the launcher. The open chat always sits above page content.                       |
| `closedButtonSize`         | `number`  | Channel setting, or `40` | Launcher button size in pixels. Values below `40` are treated as `40`.                                                                                                            |
| `showChannelLogo`          | `boolean` | `false`                  | Shows the channel logo inside the launcher button instead of the chat icon. The logo is set in the channel's appearance settings.                                                 |
| `hideCloseButton`          | `boolean` | `false`                  | Hides the close button inside the chat, so visitors cannot close it themselves. Use this only when your page closes the chat with `ChatWidget.close()`.                           |
| `twoStepOpen`              | `boolean` | Channel setting          | When `true`, the first launcher click shows a small intro card, and the chat opens from the card's start button. Calls to `ChatWidget.open()` always open the chat directly.      |

## Settings managed in Sagepilot

These come from the channel settings. Change them in Sagepilot under **Channels** > your widget. See [Website Widget](/integrations/channels/website-widget).

| Area                            | Examples                                                                                                                                 |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Appearance                      | Accent color, logo, button text, launcher position (left or right), default bottom padding, and launcher size.                           |
| Messages                        | Welcome popup message, greeting, main call to action, and conversation starters.                                                         |
| Behavior                        | Welcome popup and its delay, two-step open, visitor tracking, image cards, link pills, and whether visitors can start new conversations. |
| Contact form and authentication | Fields visitors fill in before chatting, and OTP verification.                                                                           |
| Identity                        | Identity verification and its secret. See [Identity](/sdks/web/identity).                                                                |

## Layout

* On screens 768 px wide or narrower, the open chat fills the whole screen. This needs a responsive viewport tag, such as `<meta name="viewport" content="width=device-width, initial-scale=1">`, in your page's `<head>`. Most modern themes already include one.
* On wider screens, it opens as a panel up to 420 px wide and 700 px tall, on the side set in the channel's launcher position.
* The layout updates when the window is resized or rotated.
* Opening the chat clears the unread badge on the launcher.