@supportwire/widget

Embed the SupportWire chat widget on your site. Load via script tag or ESM; configure theme, position, and optional JWT auth. Supports hidden trigger on launch, programmatic open/close, and sending messages.

Install

npm install @supportwire/widget

Usage

Option 1: Script tag (no bundler)

Load the IIFE build from a CDN, then create the widget with your config.

<script src="https://assets.supportwire.app/supportwire/widget-app-assets/loader/index.iife.js"></script>
<script>
  const widget = new (window.SupportWireWidget?.default ?? window.SupportWireWidget)({
    appUrl: 'https://your-widget-app.com',  // URL of your SupportWire widget app
    domain: 'your-org',
    widgetId: 'your-widget-id',
    theme: 'light',
    triggerPosition: 'bottom-right',
    widgetType: 'popup',
    userToken: 'optional-jwt-for-identified-users',
    onOpen: () => console.log('Opened'),
    onClose: () => console.log('Closed'),
    onError: (err) => console.error(err)
  });
</script>

Option 2: ESM (with a bundler)

import SupportWireWidget from '@supportwire/widget';

const widget = new SupportWireWidget({
  domain: 'your-org',
  widgetId: 'your-widget-id', // make it unique for each widget instance
  theme: 'light', // 'light' or 'dark'
  triggerPosition: 'bottom-right',
  widgetType: 'popup', // 'popup' or 'drawer' or 'center modal'
  userToken: 'optional-jwt', // JWT for identifying the user in the widget
  onOpen: () => {}, // Callback when the widget is opened
  onClose: () => {}, // Callback when the widget is closed
  onError: (err) => console.error(err) // Callback when the widget encounters an error
});

Config

| Option | Required | Description | |--------|----------|-------------| | appUrl | Yes (when using the npm build) | Base URL of the widget app (e.g. https://widget.supportwire.app) | | domain | Yes | Your organization slug | | widgetId | Yes | Your widget ID | | theme | No | 'light' or 'dark' (default: 'light') | | triggerPosition | No | 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | | widgetType | No | 'popup' | 'drawer' | 'center modal' | | userToken | No | JWT for identifying the user in the widget | | hideOnLaunch | No | If true, the trigger is hidden on load. Use showTrigger() to show it, or open the widget via open() / sendMessage() — opening the widget also shows the trigger (default: false) | | selector | No | CSS selector for a custom trigger element (if not set, the default floating button is used) | | onOpen / onClose / onError | No | Callbacks |

API

Instance methods

• widget.open() – open the widget
• widget.close() – close the widget
• widget.toggle() – open if closed, close if open
• widget.showTrigger() – show the trigger (e.g. after hiding with hideOnLaunch)
• widget.hideTrigger() – hide the trigger
• widget.sendMessage(message, { openWidget?: boolean }) – send a message (markdown); opens the widget by default (and shows the trigger if hidden) unless { openWidget: false } is passed
• widget.updateConfig(partialConfig) – update config at runtime
• widget.destroy() – remove the widget from the page

Static methods

• SupportWireWidget.getInstances(widgetId?) – returns all initialized widget instances; if widgetId is passed, only instances for that widget ID. Useful when multiple widgets exist or the constructor reference was not stored.