For App Developers
Settings Reference
HilChatWindowSettings is the one object that configures everything about how HilChatWindow behaves — every field is optional, so an app only needs to specify what it wants to change from the default.
The Shipped Default
Passing defaultChatSettings as-is gives a fully working, zero-config chat window:
export const defaultChatSettings: HilChatWindowSettings = {
actionBar: { presetClickBehavior: 'send' },
visibility: { header: true, timestamps: true, avatars: true, presetRow: true, actionBar: true },
mount: { mode: 'overlay' },
windowControls: { fullscreen: false, dock: false, minimize: false, close: true },
};To customize, spread it and override just the fields you need:
<HilChatWindow settings={{ ...defaultChatSettings, visibility: { ...defaultChatSettings.visibility, avatars: false } }} />Field Reference
| Field | Type | What it controls |
|---|---|---|
messageFilter | (message) => boolean | Which messages this instance renders at all. Return false to hide a message entirely. Default: render everything. |
renderers | { text?, form? } | Per-message-kind renderer override. See Custom Renderers. |
actionBar.defaultActions | array | Extra action buttons always shown, in addition to whatever the current request itself provides. |
actionBar.presetClickBehavior | 'send' | 'fill' | Clicking a quick-reply chip either sends it immediately ('send', the default) or fills the text box for the person to edit before sending ('fill'). |
api.formFetchURL | string | Endpoint the chat window's built-in inline-form renderer uses to fetch a form's schema by ID, when your app hasn't already registered its own form renderer (see Quick Start step 5). |
api.authTokenProvider | () => string | null | Supplies the auth token used for that fallback fetch, instead of the window reading it from a fixed storage location itself. Lets each app decide where its own token lives. |
visibility.header | boolean | Show/hide the title bar (title, countdown, window controls) entirely. |
visibility.timestamps | boolean | Reserved toggle for message timestamps — present in the settings shape, not yet rendered by the shipped bubble in this release. |
visibility.avatars | boolean | Show/hide the sender initial (S/U) beside each bubble. |
visibility.presetRow | boolean | Show/hide the quick-reply chip row above the text box. |
visibility.actionBar | boolean | Show/hide the action-button row below the composer. |
theme | Record<string, string> | CSS custom-property overrides applied on top of the window's default theme. See Mount Modes & Theming. |
mount.mode | 'overlay' | 'docked' | 'inline' | Where and how the window renders. Default: 'overlay'. See Mount Modes & Theming. |
mount.attachTo | string (CSS selector) or element | Required when mount.mode is 'docked' — the container the window portals into. |
windowControls.fullscreen | boolean | Show/hide the fullscreen icon in the header. |
windowControls.dock | boolean | Show/hide the dock icon in the header. |
windowControls.minimize | boolean | Show/hide the minimize icon in the header. |
windowControls.close | boolean | Show/hide the close icon. Requires an onClose prop on HilChatWindow to actually be clickable — otherwise it renders disabled. |
Icon visibility vs. behavior
The
fullscreen, dock, and minimize window-control flags currently only control whether the icon is shown — clicking them does nothing yet, since no behavior has been wired up for them in this release. Only close is functional, and only once you supply an onClose handler.
Message Filtering Example
Hide form-kind messages entirely for an app that doesn't support rendering inline forms yet:
const settings: HilChatWindowSettings = {
...defaultChatSettings,
messageFilter: (message) => message.kind !== 'form',
};Supplying a Form Endpoint Example
const settings: HilChatWindowSettings = {
...defaultChatSettings,
api: {
formFetchURL: `${apiConfig.baseUrl}/api/v1/atlas/forms/by-id`,
authTokenProvider: () => myAuthStore.getToken(),
},
};