Configuration - Sagepilot Docs

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.

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

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.

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.