@aplisay/react-widget

A React component for integrating Aplisay's conversational AI into your web applications.

Installation

npm install @aplisay/react-widget

Basic Usage

import React from 'react';
import '@aplisay/react-widget/dist/styles.css';
import { AplisayWidget } from '@aplisay/react-widget';

function App() {
  return (
    <AplisayWidget
      listenerId="YOUR_LISTENER_ID"
      url="YOUR_APLISAY_URL"
      roomKey="YOUR_ROOM_KEY"
      debug={true}
      showStatus={true}
      theme={{
        palette: {
          mode: 'light',
          primary: {
            main: '#f63bcb'
          },
          background: {
            default: '#ffffff'
          },
          text: {
            primary: '#374151'
          },
          error: {
            main: '#ef4444'
          }
        }
      }}
    />
  );
}

Script-tag embed (no React required)

Sites that don't use React (or don't want a build step) can embed the widget with a single script tag. The tag injects a small (~5 KB) launcher button; the full widget loads inside an iframe only when a visitor opens it, so it adds no meaningful weight to your page.

<script async src="https://widget.aplisay.com/embed/v1.js"
  data-listener-id="YOUR_LISTENER_ID"
  data-room-key="YOUR_ROOM_KEY"
  data-primary-color="#f63bcb"
  data-launcher-label="Talk to us"></script>

Data attributes

| Attribute | Default | Description | | --------------------- | -------------------------------- | -------------------------------------------------- | | data-listener-id | — | Required. Listener id from the Aplisay platform | | data-room-key | — | Required. Room key from the Aplisay platform | | data-url | https://llm-agent.aplisay.com | Aplisay API endpoint | | data-frame-url | https://widget.aplisay.com/framed | Frame page (override when self-hosting) | | data-mode | light | light or dark | | data-primary-color | #f63bcb | Accent colour | | data-background-color | #ffffff | Panel background | | data-text-color | #374151 | Text colour | | data-position | bottom-right | bottom-right or bottom-left | | data-offset-x / data-offset-y | 24 | Distance from the viewport edges, px | | data-z-index | 2147482000 | Stacking order of launcher and panel | | data-launcher-label | Talk to us | Launcher text; empty for an icon-only button | | data-launcher-color | primary colour | Launcher background | | data-width / data-height | 380 / 560 | Panel size, px (full-screen on small viewports) | | data-show-status | off | Show connection status while connected | | data-debug | off | Verbose logging |

JavaScript API

The loader installs a window.aplisay(command, …) function. To call it before the (async) script has loaded, use the standard queue stub:

<script>
  window.aplisay = window.aplisay || function () {
    (window.aplisay.q = window.aplisay.q || []).push(arguments);
  };
</script>

| Command | Effect | | ------- | ------ | | aplisay('init', config) | Initialise programmatically (same keys as the data attributes, camelCased) — for SPAs or deferred credentials | | aplisay('open') / aplisay('close') / aplisay('toggle') | Control the panel. Closing removes the iframe, which ends any call in progress | | aplisay('on', type, fn) / aplisay('off', type, fn) | Subscribe to events: open, close, plus any { type: … } message posted by the widget frame | | aplisay('destroy') | Remove the widget entirely |

Bundler users can get the same launcher without React via import '@aplisay/react-widget/embed'.

Props

| Prop | Type | Required | Description | | ------------ | ----------------------------- | -------- | ---------------------------------------- | | listenerId | string | Yes | Your unique listener identifier | | url | string | Yes | The Aplisay API endpoint URL | | roomKey | string | Yes | Authentication key for the room | | debug | boolean | No | Enable detailed logging (default: false — the widget logs nothing without it) | | showStatus | boolean | No | Show connection status (default: false) | | theme | Theme Object | No | Custom theme configuration (defaults to the light theme) |

Missing or invalid required props never throw: the widget renders a Configuration error state and logs a single console.warn, so a misconfigured embed can't break the page hosting it.

Controlled Mode

If you wish, the widget can be controlled by the open prop. The setter, setOpen, will be called with the new state of the widget if it changes due to user interaction (pressing hangup, etc).

| Prop | Type | Required | Description | | --------- | ----------------------- | -------- | ---------------------------------------------- | | open | boolean | No | Whether the widget is active (default: true) | | setOpen | (open: boolean) => void | No | Function to set the widget's open/active state |

Theme Object

interface Theme {
  palette: {
    mode?: 'light' | 'dark';
    primary?: {
      main?: string; // Primary color
    };
    background?: {
      default?: string; // Background color
    };
    text?: {
      primary?: string; // Text color
    };
    error?: {
      main?: string; // Error color
    };
  };
}

Advanced Styling

This theme doesn't provide enough customization for your needs? Feel free to customize the appearance of the widget using your own CSS overrides. Note, however, that the CSS class names provided by @aplisay/react-widget are not considered stable and may change in future versions.

Room States

The widget can be in one of these states:

• initial
• parameter_error
• join
• connected
• error

Additional Exports

import { useAplisayRoom } from '@aplisay/react-widget';

useAplisayRoom Hook

The useAplisayRoom hook provides a way to integrate Aplisay's conversational AI into your React application with more control over the room state and functionality.

Parameters

| Parameter | Type | Required | Description | | --------------- | ----------------------------- | -------- | ---------------------------------------------- | | url | string | No | The Aplisay API endpoint URL | | listenerId | string | No | Your unique listener identifier | | roomKey | string | No | Authentication key for the room | | joinCallback | () => Promise | No | Custom function to handle room joining | | clientFunctions| { [key: string]: Function } | No | Custom functions to be registered with the session | | close | boolean | No | Whether to close the room connection |

Either the url, listener and roomKey should be specified to allow the hook to call the server and instantiate a room OR a function passed in joinCallback which will be called to execute the room join.

Returns

| Property | Type | Description | | ----------- | ------------------- | ---------------------------------------------- | | state | RoomState | Current state of the room ('initial', 'parameter_error', 'join', 'connected', 'error') | | agentState| string | Current state of the AI agent | | error | string | Error message if any | | transcript| TranscriptEntry[] | Array of conversation transcript entries | | room | RoomData | Room connection data from join request. Primary useful property is callId which isn't otherwise obtainable |

Example Usage

import { useAplisayRoom } from '@aplisay/react-widget';

function CustomWidget() {
  const { state, agentState, error, transcript, room } = useAplisayRoom({
    url: 'YOUR_APLISAY_URL',
    listenerId: 'YOUR_LISTENER_ID',
    roomKey: 'YOUR_ROOM_KEY',
    clientFunctions: {
      // Register custom functions here
      myCustomFunction: (args) => {
        // Handle custom function call
        return 'Result';
      }
    }
  });

  // Use the hook's return values to build your custom UI
  return (
    <div>
      {state === 'connected' && (
        <div>
          <p>Agent State: {agentState}</p>
          <div className="transcript">
            {transcript.map((entry, index) => (
              <p key={index}>{entry.speaker}: {entry.text}</p>
            ))}
          </div>
        </div>
      )}
      {error && <p className="error">{error}</p>}
    </div>
  );
}

Live Demo/Configurator

Configurator | Configurator Source Code

Support

For issues, feature requests, or questions, please just use this repo. Open An Issue in the first instance.

License

MIT License, for any code written by Aplisay for this widget.