Widget Configuration

Customize how the Appilot Widget behaves on your site.

What is configurable

Every option in the table below is read by the shipped widget. Options that need a future release are marked in place. Each one has a data-* attribute on the script tag and a matching camelCase field on bootAppilotWidget.

Configuration options

Option	Type	Required	Default	Description
`apiKey`	`string`	Conditional	n/a	Widget API key (`wk_live_...` or `wk_test_...`). Optional on a registered domain; required for `localhost`/dev and server-to-server. See Do I need an API key?
`apiUrl`	`string`	No	The host the bundle was built for (`https://api.appilot.space` for the CDN build)	Backend REST API URL (set for on-premise)
`position`	`string`	No	`"bottom-right"`	Widget position: `bottom-right`, `bottom-left`
`theme`	`string`	No	`"auto"`	Color theme: `auto` (follows the OS), `light`, `dark`, or `host` (follows your site's own light/dark state). See Theming & dark mode
`language`	`string`	No	`"auto"`	UI language: `en`, `es`, `de`, or `auto` (detects from `<html lang>`)
`autoOpen`	`boolean`	No	`false`	Open the panel automatically on page load
`collapsed`	`boolean`	No	`false`	Start with the launcher hidden. Open the panel yourself with `Appilot.open()`
`zIndex`	`number`	No	`9999`	CSS z-index for the widget
`piiMasking`	`boolean`	No	`true`	Enable client-side PII masking
`userAuth`	`boolean`	No	`false`	Show the built-in Appilot sign-in form when no identity is present. When disabled and no `userToken` is passed, the panel shows a "Sign in to continue" notice instead. See Identity & Sign-in
`userToken`	`string`	No	n/a	Pre-authenticated user token from the federation handshake (`data-user-token`). See Connecting your users
`docsBaseUrl`	`string`	No	`https://docs.appilot.space`	Documentation root for in-panel help links (`data-docs-base-url`). Override for on-premise deployments that self-host these docs
`setupHints`	`boolean`	No	`false`	Show Appilot's integrator guidance inside the panel (`data-setup-hints`). Off by default, because your visitors read the panel: the same guidance always reaches you on the browser console. Turn it on while you wire the widget up
`accent`	`string`	No	Appilot cyan	Brand accent color (`data-accent`), applied to both themes. See Brand color
`accentDark`	`string`	No	Falls back to `accent`	Dark-mode brand accent (`data-accent-dark`)
`brandName`	`string`	No	Org name	Header brand text override (`data-brand-name`)
`width`	`string`	No	`400px`	Bubble width (`data-width`); bare number = px
`height`	`string`	No	`min(680px, 100vh - 112px)`	Bubble height (`data-height`); any CSS length
`layout`	`string`	No	`"bubble"`	Panel placement (`data-layout`): `bubble`, `sidebar`, `inline`, `detached`. See Layout modes
`container`	`string`	No	n/a	Selector the `inline` layout mounts into (`data-container`, e.g. `#assistant`)

Why no orgId?

The organization is derived from your domain on a registered site (and from your API key on localhost/server-to-server). You never set an orgId: there is no way to misconfigure a wrong org, and your configuration stays minimal.

Script tag configuration

All options are set via data-* attributes:

<script type="module"
  src="https://cdn.appilot.space/widget/v1/appilot.esm.js"
  data-api-key="wk_live_a1b2c3d4..."
  data-position="bottom-left"
  data-theme="host"
  data-language="es"
  data-auto-open="true"
  data-z-index="10000"
  data-pii-masking="true"
  data-user-auth="false"
  data-accent="#e0457b"
  data-brand-name="Acme Support"
  data-width="420"
  data-height="90vh"></script>

note

Add a matching <script nomodule src=".../appilot.js" ...> line with the same data-* attributes for browsers without ES module support. See Installation for the full two-line snippet.

JavaScript API configuration

Boot the widget from your bundler with bootAppilotWidget (from appilot):

import { bootAppilotWidget } from 'appilot';

bootAppilotWidget({
  widgetScriptUrl: 'https://cdn.appilot.space/widget/v1/appilot.esm.js',
  widgetKey: 'wk_live_a1b2c3d4...',
  tokenEndpoint: '/api/widget/token',
  position: 'bottom-left',
  theme: 'dark',
  language: 'es',
});

Every option in the table above has a camelCase field on bootAppilotWidget with the same meaning, so a bundler integration needs no script tag of its own. What you do not pass is not stamped on the tag at all, which leaves the bundle's own defaults in place. Full option list: API Reference.

On-premise configuration

For self-hosted deployments, set apiUrl to point to your own Appilot backend:

<script
  src="/assets/appilot.js"
  data-api-key="wk_live_a1b2c3d4..."
  data-api-url="https://appilot.internal.company.com"
  async
></script>

Or via JavaScript:

bootAppilotWidget({
  widgetScriptUrl: 'https://cdn.appilot.space/widget/v1/appilot.esm.js',
  widgetKey: 'wk_live_a1b2c3d4...',
  appilotApiUrl: 'https://appilot.internal.company.com',
});

What else an on-premise deployment involves, including the MCP server and the language model, is in On-premise.

Changing configuration at runtime

Two things change without a remount, and they are the two users notice:

window.Appilot.setTheme('dark');
window.Appilot.setLanguage('de');

Both preserve the conversation on screen. Anything else (the position, the layout, the key) is fixed at boot. To change one, call window.Appilot.initAppilot(config) with the new configuration: it replaces the current instance rather than adding a second one, and the panel starts fresh. There is no updateAppilot.

The hamburger menu inside the panel gives the end user:

Knowledge Base: the content available for the current page.
Conversation History: past conversations (shown once the user is identified, whether through userToken federation or the built-in login).
Settings: language, light/dark theme, and a Show Page Inspector toggle.
Layout / Pop out: switch between bubble and sidebar, or pop the panel out to drag and resize it (see Layout modes).

Page Inspector (enabled from Settings) is a troubleshooting view: it shows what Appilot detected on the current page (forms, fields, links, buttons, detected view) and lets you locate any of them on the page. It is useful when verifying that a page is correctly recognized.

Explaining a field to the assistant

Nothing in the page markup is read as an instruction to the assistant. What a field means belongs in your configuration, where you can review it and translate it: register the field as a Control with a description, or write the rule as knowledge scoped to the view. See Managing controls.

Identifying your users

Appilot attributes every conversation to an identified user: there is no anonymous usage, so the widget will not chat until a user is identified (no opt-out). When neither field below is set, the panel shows a "Sign in to continue" notice instead of the assistant; Identity & Sign-in walks through what the panel shows per configuration and how to fix that notice. The full federation model (with copy-paste examples) lives in Connecting your users; the two config fields it uses are summarized here.

Federation (the common case): `userToken`

Your backend exchanges your widget key + server secret + the user's id for a short-lived Appilot token, then hands it to the widget. Your users never see an "Appilot account":

bootAppilotWidget({
  widgetScriptUrl: 'https://cdn.appilot.space/widget/v1/appilot.esm.js',
  // widgetKey optional on a registered domain
  tokenEndpoint: '/api/widget/token', // your backend mints the identified token here
  getBearer: () => getMyAppSessionToken(), // federates the logged-in user
});

bootAppilotWidget re-relays through tokenEndpoint before the token expires, so the widget stays authenticated for the life of the page. If your app authenticates only after boot, the loaded widget also exposes Appilot.setUserToken(token).

Built-in Appilot login: `userAuth`

If you have no user accounts at all, enable the widget's built-in login/register so users sign in with an Appilot account directly in the panel. This is a bundle-level option, set with the data-user-auth attribute on the script tag:

<script type="module"
  src="https://cdn.appilot.space/widget/v1/appilot.esm.js"
  data-user-auth="true"></script>

The signed-in account must be an active member of the organization that owns the widget; see Built-in sign-in for when to choose this over federation.

For enterprise SSO (OIDC / SAML) and extension account linkage, see Connecting your users and Account Linkage.

Content Security Policy

If your application uses CSP headers, ensure the following sources are allowed:

Content-Security-Policy:
  script-src 'self' https://cdn.appilot.space;
  connect-src 'self' https://api.appilot.space;
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://cdn.appilot.space;

For on-premise deployments, replace the Appilot URLs with your self-hosted equivalents.

Configuration options​

Script tag configuration​

JavaScript API configuration​

On-premise configuration​

Changing configuration at runtime​

In-panel menu​

Explaining a field to the assistant​

Identifying your users​

Federation (the common case): userToken​

Built-in Appilot login: userAuth​

Content Security Policy​