Widgets

Installation

Via npm for apps with a build step:

npm install xpectrum

Or with no build step at all — one script tag (see Embed scripts below).

1. ChatWidget

A floating launcher that opens a chat window: streaming replies, Markdown rendering, and a greeting from your app's configured opening statement. It opens straight into a fresh conversation — no history is shown or loaded, so it is safe to use with a key that has history access disabled.

import { ChatWidget } from 'xpectrum';

new ChatWidget({
  baseUrl: 'https://cloud.xpectrum.dev/v1',
  apiKey: 'xpectrum_...',
  welcomeMessage: 'Hi! How can I help?',
  logo: 'https://yoursite.com/logo.png',
  title: 'Acme Support',
  primaryColor: '#7C3AED',
});

Branding & identity

Theme & layout

2. VoiceWidget

A voice-assistant call card, not a chat window: a floating launcher opens a compact card with an animated orb. Tap the orb to start the call. While the agent speaks, a live analyser reads its audio and drives the orb and the coloured waves around it, so the motion follows the actual sound. Status text ("Listening… / Speaking…"), a call timer, a one-line caption of what was last said, and round mute / end-call controls complete the card.

import { VoiceWidget } from 'xpectrum';

new VoiceWidget({
  baseUrl: 'https://cloud.xpectrum.dev/v1',
  apiKey: 'xpectrum_...',
  position: 'bottom-right',
  buttonColor: '#7C3AED',
});

3. OmnichannelWidget

One launcher for both channels. Clicking it opens a small menu — Chat and Voice Call — and each option opens the matching widget. Use it when a page should offer both ways to talk without two floating buttons.

import { OmnichannelWidget } from 'xpectrum';

new OmnichannelWidget({
  chatBaseUrl: 'https://cloud.xpectrum.dev/v1',
  chatApiKey: 'xpectrum_...',
  voiceBaseUrl: 'https://cloud.xpectrum.dev/v1',
  apiKey: 'xpectrum_...',
  position: 'bottom-right',
  buttonColor: '#7C3AED',
});

4. Methods

Every widget instance exposes the same small API:

const widget = new ChatWidget({ ... });

widget.open();     // open the window / card
widget.close();    // close it (a live voice call is hung up cleanly)
widget.toggle();   // flip between open and closed
widget.destroy();  // remove the widget from the page entirely

5. Embed scripts — no build step

For WordPress, Shopify, or any plain HTML site: define a small config object, include one script tag, done. The script loads the SDK and mounts the widget by itself.

Chat

<script>
  window.XpectrumChatConfig = {
    apiKey: 'xpectrum_...',
    baseUrl: 'https://cloud.xpectrum.dev/v1',
    // Optional branding:
    logo: 'https://yoursite.com/logo.png',
    title: 'Acme Support',
    welcomeMessage: 'Hi! How can I help?',
    primaryColor: '#7C3AED',
    theme: 'light',
  };
</script>
<script src="https://unpkg.com/xpectrum@1.0.0/dist/chat-embed.min.js" defer></script>

Voice

<script>
  window.XpectrumVoiceConfig = {
    apiKey: 'xpectrum_...',
    baseUrl: 'https://cloud.xpectrum.dev/v1',
    buttonColor: '#7C3AED',
  };
</script>
<script src="https://unpkg.com/xpectrum@1.0.0/dist/voice-embed.min.js" defer></script>

Every option from the widget tables above can be set on the config object — logo, colours, fonts, position, all of it.

6. Your API key in a widget

A widget runs in the visitor's browser, so the API key is visible to anyone who opens developer tools — that is inherent to every client-side widget. Limit what an exposed key can do in your app's publish settings:

• Keep Conversation history over API switched off — the widget never needs it, and an exposed key then cannot read any transcripts.
• Switch Voice calls off for apps that only chat.

The widgets are built for this: chat opens fresh conversations without touching history endpoints, and the voice agent is fixed by the key itself — a caller cannot pick a different agent.