JavaScript Widget SDK

The widget SDK accepts a non-secret public installation ID. It is published as a bundle at <your-keva-origin>/widget/v1/keva-widget.js — see Widget Installation Boundary. The examples below describe the interfaces that bundle exposes.

Initialization source shape

interface KevaInitOptions {
  publicId: string;
  apiUrl?: string;
  user?: { email?: string; name?: string };
  nonce?: string;
  mode?: 'chat' | 'form' | 'hybrid';
  primaryColor?: string;
  intakeModes?: {
    paste?: boolean;
    voice?: boolean;
    screenshot?: boolean;
    recording?: boolean;
  };
}

nonce is optional. On a strict-CSP site, pass the per-response nonce used to authorize the script and style-src; the SDK applies it to the widget's shadow stylesheet. The default remains unchanged when nonce is omitted. For example:

window.Keva.init({
  publicId: 'keva_widget_…',
  nonce: responseNonce,
});

publicId is publishable but not sufficient by itself to read an existing conversation. The SDK exchanges it from an allowed origin, stores the returned session only in memory, and adds that session to widget API requests as an authorization header.

The install snippet's data-public-id is what the bundle self-initializes from; window.Keva.init({ publicId: 'keva_widget_…' }) is the equivalent when you load the bundle yourself. The installed-widget journey is not available for customer use yet.

Instance methods

After successful initialization, source exposes:

interface KevaWidgetInstance {
  open(): void;
  close(): void;
  toggle(): void;
  destroy(): void;
  setUser(user: { email?: string; name?: string }): void;
  on(event: WidgetEvent, callback: (data: unknown) => void): () => void;
}

Supported source events are ready, open, close, conversationStarted, messageSent, messageReceived, form-extracted, form-submitted, and error.

Current limitations

• Session lifetime is 15 minutes. The SDK does not renew a session or resume a bound conversation after expiry.
• Streaming uses authenticated fetch with polling fallback, but browser-real reconnect and revocation behavior are not available for customer use yet.
• Redis outage causes the shared throttle to allow requests, so published rate guarantees and paid-provider abuse containment remain unresolved.
• Calling open, close, or setUser before initialization finishes only updates pending local state; it does not prove that the server journey is available.

Singleton behavior

Current source permits one widget instance. Initializing another instance destroys the previous local instance. This describes the current application behavior; it does not mean the deployed product is available.