Sentifyd Realtime - NPM Package

Conversational AI chatbot with 3D avatar for React, Vue, Next.js, and modern web frameworks. Visit https://sentifyd.io to create your avatar and get its API key.

Table of Contents

• Installation
• Quick Start
• Framework Examples
• Configuration
• TypeScript Support
• Styling
• API Reference

Installation

npm install sentifyd-realtime

or

yarn add sentifyd-realtime

Vite Configuration (Required)

This package requires a Vite plugin to correctly handle the 3D avatar's assets and audio worklets. Add the plugin to your vite.config.js:

import { defineConfig } from 'vite';
import { sentifydRealtimePlugin } from 'sentifyd-realtime/vite-plugin';

export default defineConfig({
  plugins: [
    sentifydRealtimePlugin()
  ]
});

This plugin ensures that:

1. Audio worklets for lip-sync are correctly served.
2. Dynamic modules from the underlying 3D engine are properly handled.

Quick Start

React

import React from 'react';
import { SentifydRealtime } from 'sentifyd-realtime/react';

function App() {
  return (
    <SentifydRealtime
      apiKey="your-api-key"
      avatarId="1"
      toggler={true}
      brandName="Your Brand"
      onReady={(bot) => console.log('Bot ready!', bot)}
    />
  );
}

export default App;

Vue 3

<template>
  <sentifyd-realtime
    :api-key="apiKey"
    :avatar-id="avatarId"
    :toggler="true"
    @sentifyd-ready="handleReady"
  />
</template>

<script setup>
import { onMounted } from 'vue';
import { registerSentifydRealtime } from 'sentifyd-realtime';

onMounted(() => {
  registerSentifydRealtime();
});

const apiKey = 'your-api-key';
const avatarId = '1';

const handleReady = (event) => {
  console.log('Bot ready!', event);
};
</script>

Vanilla JavaScript

import { createSentifydRealtime } from 'sentifyd-realtime';

const bot = createSentifydRealtime({
  apiKey: 'your-api-key',
  avatarId: '1',
  toggler: true,
  brandName: 'Your Brand'
});

Next.js

'use client'; // For Next.js 13+ App Router

import dynamic from 'next/dynamic';

const SentifydRealtime = dynamic(
  () => import('sentifyd-realtime/react').then(mod => mod.SentifydRealtime),
  { ssr: false }
);

export default function Home() {
  return (
    <main>
      <h1>Welcome</h1>
      <SentifydRealtime
        apiKey="your-api-key"
        avatarId="1"
        toggler={true}
      />
    </main>
  );
}

Configuration

Required Props

• apiKey (string): Your Sentifyd API key
• avatarId (string): The avatar ID to use

Optional Props

• toggler (boolean, default: true): Show the toggler button
• compact (boolean, default: false): Use compact layout
• brandName (string): Brand name to display
• brandLogo (string): Brand logo URL
• termsHref (string): Terms of service URL
• privacyHref (string): Privacy policy URL
• enableCaptions (boolean, default: false): Enable live captions

React Component Events

• onReady (function): Callback when bot is ready
• onError (function): Callback when an error occurs
• onOpen (function): Callback when bot is opened
• onClose (function): Callback when bot is closed

Package Details

• Dependencies: Lit, Socket.IO Client, TalkingHead, XState, and utilities (installed automatically)
• Peer Dependencies: React (optional for non-React users)
• Exports: ESM module with tree-shakable exports

Styling

Customize the bot's appearance using CSS custom properties:

sentifyd-realtime {
  --primary-color: #3b82f6;
  --secondary-color: #569abd;
  --text-color-primary-bg: #ffffff;
  --text-color-secondary-bg: #222222;
}

TypeScript Support

The package includes full TypeScript definitions:

import type { 
  SentifydRealtimeConfig, 
  SentifydStorage 
} from 'sentifyd-realtime';

// For React
import type { 
  SentifydRealtimeProps, 
  SentifydRealtimeHandle 
} from 'sentifyd-realtime/react';

API Reference

registerSentifydRealtime()

Register the web component globally. Call once before using <sentifyd-realtime>.

createSentifydRealtime(config)

Programmatically create and mount a bot instance.

Parameters:

• config (object): Configuration options

Returns: HTMLElement

initializeStorage(storage)

Configure custom storage (for mobile apps or special use cases).

Parameters:

• storage (object): Storage adapter with getItem, setItem, removeItem methods

Support

• Website: https://sentifyd.io
• Email: [email protected]

License

Proprietary - See LICENSE.md for details.

Free to use in commercial and non-commercial projects. Modification and redistribution of source code prohibited without permission.

Changelog

See CHANGELOG.md for a full list of changes.