Widget API Reference

The Appilot Widget exposes a JavaScript API for programmatic control.

Current status

The widget is in Phase 0.1 (MVP). Currently available: initAppilot() and destroyAppilot() via script tag with data-* attributes. Features marked as Planned below require a future release.

Initialization

initAppilot(config)

Initialize the widget. Must be called once. Subsequent calls are ignored (idempotent).

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

initAppilot({
  apiKey: 'wk_live_a1b2c3d4...',
  theme: 'dark',
});

Parameters:

Field	Type	Required	Description
apiKey	string	Yes	Widget API key
apiUrl	string	No	Backend URL (default: https://api.appilot.com)
wsUrl	string	No	WebSocket URL (auto-derived from apiUrl)
position	'bottom-right' | 'bottom-left'	No	Button position
theme	'light' | 'dark' | 'auto' | 'host'	No	Color theme. auto follows the OS; host follows your site. See Theming & dark mode
language	'en' | 'es' | 'de' | 'auto'	No	UI language
autoOpen	boolean	No	Open panel on load
collapsed	boolean	No	Hide button initially
zIndex	number	No	CSS z-index
piiMasking	boolean	No	Enable PII masking
userAuth	boolean	No	Enable the built-in sign-in form. See Identity & Sign-in
userToken	string	No	Pre-authenticated JWT
docsBaseUrl	string	No	Documentation root for in-panel help links (on-premise override)

Returns: void

destroyAppilot()

Remove the widget from the page and clean up all resources (WebSocket, event listeners).

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

destroyAppilot();

updateAppilot(config)

Coming soon

updateAppilot is planned for a future release.

Update widget configuration at runtime. Only the provided fields are changed.

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

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

Panel Control

Coming soon

Programmatic panel control (open, close, toggle, isOpen) is planned for a future release.

Appilot.open()

Open the assistant panel.

Appilot.open();

Appilot.close()

Close the assistant panel.

Appilot.close();

Appilot.toggle()

Toggle the panel open or closed.

Appilot.toggle();

Appilot.isOpen()

Check if the panel is currently open.

const open = Appilot.isOpen(); // boolean

Theme control

Appilot.setTheme(mode)

Set the theme policy at runtime: 'light' | 'dark' | 'auto' | 'host'. Takes effect immediately without re-mounting the widget, so the open conversation is preserved. Use it to keep the assistant in lockstep with your own theme toggle.

// Wire it to your app's light/dark toggle:
myThemeToggle.addEventListener('change', (e) => {
  window.Appilot.setTheme(e.target.checked ? 'dark' : 'light');
});

See Theming & dark mode for the full model, including the no-code data-theme="host" option.

Messaging

Coming soon

Programmatic messaging (sendMessage, setContext) is planned for a future release.

Appilot.sendMessage(text)

Programmatically send a message to the assistant. Opens the panel if closed.

Appilot.sendMessage('How do I fill out the tax ID field?');

Appilot.setContext(context)

Provide additional context for the assistant. This is merged with the auto-detected page context.

Appilot.setContext({
  page: 'checkout',
  step: 3,
  user: { plan: 'enterprise' },
});

Events

Coming soon

Event subscriptions (Appilot.on) are planned for a future release.

Appilot.on(event, callback)

Subscribe to widget events. Returns an unsubscribe function.

const unsubscribe = Appilot.on('message', (data) => {
  console.log('Assistant replied:', data.text);
});

// Later: stop listening
unsubscribe();

Available events

Event	Payload	Description
ready	{}	Widget initialized and ready
open	{}	Panel opened
close	{}	Panel closed
message	{ text, role, timestamp }	Message sent or received
error	{ code, message }	Error occurred

Global Object

When loaded via script tag (IIFE), the widget exposes window.Appilot:

<script src="https://cdn.appilot.com/widget/v1/appilot.js" data-api-key="wk_live_..." async></script>
<script>
  window.addEventListener('appilot:ready', function () {
    Appilot.open();
    Appilot.sendMessage('Help me with this form');
    Appilot.on('message', function (data) {
      console.log(data.text);
    });
  });
</script>

Federated (delegated) Authentication

To authenticate users without showing a login UI, your backend mints a short-lived Appilot token via the federation handshake and passes it to the widget. This is the common case; the full walkthrough is in Connecting your users.

Backend call

The handshake requires your server secret (wsk_secret_...), which is private and lives only on your backend. The public key alone cannot mint a user token.

curl -X POST https://api.appilot.com/widget/token \
  -H "X-Widget-Key: wk_live_a1b2c3d4..." \
  -H "X-Widget-Secret: wsk_secret_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "your-app-user-id", "email": "user@example.com", "displayName": "Jane" }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 3600
}

Frontend usage

// Your backend performs the handshake and returns the token
const response = await fetch('/api/appilot-token');
const { token } = await response.json();

initAppilot({
  // apiKey optional on a registered domain
  userToken: token,
});

caution

POST /widget/token uses your server secret and MUST run on your backend, never in the browser. The public widget key alone cannot mint a user token.

TypeScript Types

The NPM package includes full TypeScript declarations:

import type { AppilotConfig, AppilotEvent } from '@appilot/widget';

const config: AppilotConfig = {
  apiKey: 'wk_live_...',
  theme: 'dark',
};