npm package

@wireface/chat is a small wrapper for apps built with a bundler. It loads widget.js from your server (so the widget always matches the server's version) and gives you the JavaScript API with TypeScript types. React components are in @wireface/chat/react (see React).

npm install @wireface/chat

import { bootWirefaceChat } from '@wireface/chat';

const chat = await bootWirefaceChat({
  host: 'https://chat.example.com', // your Wireface Chat server
  bot: 'pk_your_bot_id',
  layout: 'panel',
  launcher: { type: 'bubble', position: 'bottom-right' },
});

chat.on('message', m => console.log(m.role, m.text));
chat.registerTool('add_to_cart', {
  description: 'Add a product to the cart',
  parameters: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
  handler: async ({ sku }) => cart.add(sku),
});

Functions

Function	What it does
bootWirefaceChat(options)	Loads widget.js (once) and starts a chat. Takes every boot option plus the load options below; host is required. Booting a bot that is already on the page returns its chat.
loadWirefaceChat(loadOptions)	Loads widget.js and resolves with window.WirefaceChat, without starting a chat.
getWirefaceChat(bot?)	The chat for a bot (or the first one) if it's on the page, else undefined.

Load options:

Option	What it does
host	Your server, e.g. https://chat.example.com (required)
version	Load the pinned widget@<version>.js instead of widget.js
integrity	Its SRI hash (sha384-...); see Pinned version and SRI
nonce	A CSP nonce for the script tag (the widget reuses it for its styles where needed)
timeoutMs	Give up loading after this long (default 15000)

Every type is exported: BootOptions, LauncherOptions, VisitorIdentity, ClientTool, ToolContext, WirefaceChatInstance, WirefaceChatGlobal, WirefaceChatEvents, ChatMessageEvent, WirefaceError, EventName, Json, JsonSchema, Layout, ThemeMode, Corner and LoadOptions.

Notes

• Browser only. The functions need window: call them from an effect, a lifecycle hook or an event handler, not during server rendering. Importing the package on the server is safe.
• It adds one script tag (with data-autoboot="false", then calls boot()), so your Content-Security-Policy needs the chat host in script-src like the script tag does. Under Trusted Types it uses a policy named wireface-chat: allow it with trusted-types wireface-chat (see CSP).
• Errors: bootWirefaceChat() rejects if widget.js can't load (wrong host, blocked by a CSP, or the timeout). Problems after that (an origin that isn't allowed, for example) arrive as error events.
• One copy of widget.js per page. Later calls reuse the copy already loaded (its version wins), but each chat still talks to the host you pass when you boot it.

Framework guides: React, Next.js, Vue, Svelte.