@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'
          }
        }
      }}
    />
  );
}

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) | | showStatus | boolean | No | Show connection status (default: false) | | theme | Theme Object | No | Custom theme configuration |

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.