Sentifyd Bot - 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-bot

or

yarn add sentifyd-bot

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 { sentifydBotPlugin } from 'sentifyd-bot/vite-plugin';

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

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 { SentifydBot } from 'sentifyd-bot/react';

function App() {
  return (
    <SentifydBot
      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-bot
    :api-key="apiKey"
    :avatar-id="avatarId"
    :toggler="true"
    @sentifyd-ready="handleReady"
  />
</template>

<script setup>
import { onMounted } from 'vue';
import { registerSentifydBot } from 'sentifyd-bot';

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

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

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

Vanilla JavaScript

import { createSentifydBot } from 'sentifyd-bot';

const bot = createSentifydBot({
  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 SentifydBot = dynamic(
  () => import('sentifyd-bot/react').then(mod => mod.SentifydBot),
  { ssr: false }
);

export default function Home() {
  return (
    <main>
      <h1>Welcome</h1>
      <SentifydBot
        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, Azure Speech SDK, 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-bot {
  --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 { 
  SentifydBotConfig, 
  SentifydStorage 
} from 'sentifyd-bot';

// For React
import type { 
  SentifydBotProps, 
  SentifydBotHandle 
} from 'sentifyd-bot/react';

API Reference

registerSentifydBot()

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

createSentifydBot(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

All notable changes to this project will be documented in this file.

[1.3.1] - 2025-12-18

Changed

• Documentation: Updated README with changelog and corrected dependencies information.

[1.3.0] - 2025-12-18

Added

• Vite Plugin: Introduced sentifydBotPlugin to handle 3D avatar assets and audio worklets automatically. This is now required for Vite-based projects.
• Documentation: Updated README with instructions for configuring the new Vite plugin.

Changed

• Dependency Management: The 3D avatar engine (@met4citizen/talkinghead) is now an external dependency managed by the package, reducing the bundle size of the main application.
• Performance: Improved asset loading strategy for 3D models and lip-sync modules.

Removed

• Removed direct dependency on three.js (now handled internally by the avatar engine).

[1.2.0] - 2025-12-17

Added

• UX Improvements: Various user experience enhancements for smoother interactions.
• Conversation Resume: Enhanced handling of resuming conversations, ensuring context is preserved across sessions.

[1.1.x] - 2025-12-07

Added

• Initial release of the Sentifyd Bot npm package.
• Support for React, Vue, and Vanilla JS.
• Core conversational AI features with 3D avatar integration.