Widget Configuration

Customize how the Appilot Widget behaves on your site.

Current status

The widget is in Phase 0.1 (MVP). Core configuration options (apiKey, apiUrl, position, theme, language, zIndex, piiMasking) are available. Options marked as Planned below require a future release.

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	`https://api.appilot.com`	Backend REST API URL (set for on-premise)
`wsUrl`	`string`	No	Auto-derived from `apiUrl`	WebSocket URL (`wss://...`)
`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 button hidden (use JS API to show, Planned)
`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.de`	Documentation root for in-panel help links (`data-docs-base-url`). Override for on-premise deployments that self-host these docs
`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`. 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.com/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

import { initAppilot } from '@appilot/widget';

initAppilot({
  apiKey: 'wk_live_a1b2c3d4...',
  position: 'bottom-left',
  theme: 'dark',
  language: 'es',
  autoOpen: true,
  zIndex: 10000,
  piiMasking: true,
});

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:

initAppilot({
  apiKey: 'wk_live_a1b2c3d4...',
  apiUrl: 'https://appilot.internal.company.com',
});

The WebSocket URL is derived automatically (https:// → wss://, appends /ws). Override it explicitly with wsUrl if your WebSocket endpoint uses a different host or path.

Dynamic configuration

Coming soon

Dynamic runtime configuration (updateAppilot) is planned for a future release.

Update configuration at runtime:

import { updateAppilot } from '@appilot/widget';

updateAppilot({
  theme: 'dark',
  language: 'de',
});

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.

Context hints

Coming soon

The data-appilot-hint attribute is planned for a future release.

Help the assistant understand your page by adding data-appilot-hint attributes to form fields:

<input
  type="text"
  name="tax_id"
  data-appilot-hint="Tax ID (RFC). Format: XXXX000000XXX. Required for Mexican residents."
/>

The widget reads these hints during DOM scanning and includes them as context when the user asks a question. This is especially useful for fields whose purpose is not obvious from the HTML alone.

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":

initAppilot({
  // apiKey optional on a registered domain
  userToken: 'eyJhbGciOiJIUzI1NiIs...', // minted by your backend via POST /widget/token
});

If your app authenticates after the page loads, init without the token and set it later with 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:

initAppilot({
  userAuth: true,
});

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.com;
  connect-src 'self' https://api.appilot.com wss://api.appilot.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' https://cdn.appilot.com;

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

Configuration options​

Script tag configuration​

JavaScript API configuration​

On-premise configuration​

Dynamic configuration​

In-panel menu​

Context hints​

Identifying your users​

Federation (the common case): userToken​

Built-in Appilot login: userAuth​

Content Security Policy​