Integrating via NPM

Use the Sentifyd npm packages to integrate an avatar into React, Vue, Next.js, or any modern JavaScript application, with full bundler integration and TypeScript support.

Two packages are available. Install the one that matches your avatar's voice mode (selected when the avatar was created):

Package	Voice mode	Component
sentifyd-bot	Standard voices	<sentifyd-bot>
sentifyd-realtime	Real-time (speech-to-speech)	<sentifyd-realtime>

The examples below use sentifyd-bot; substitute sentifyd-realtime (and the matching import names) for real-time avatars.

Before you start, create and train an avatar on the Sentifyd platform, note its avatar ID and API key, and add your site's domain to the avatar's allowed domains (see the Quick Start Guide). The avatar will refuse to connect from domains that are not allowed.

One avatar per page. Render exactly one Sentifyd component per page. Mounting two components on the same page (in different parts of your component tree, or via a layout that renders twice) is not supported and will cause failures.

Installation

npm install sentifyd-bot
# or
yarn add sentifyd-bot

Vite Configuration (Required)

The package requires a Vite plugin to correctly serve the 3D avatar's assets and the audio worklets used for lip-sync. Add it to your vite.config.js:

import { defineConfig } from 'vite';
import { sentifydBotPlugin } from 'sentifyd-bot/vite-plugin';

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

For sentifyd-realtime, import sentifydRealtimePlugin from sentifyd-realtime/vite-plugin instead.

Framework Examples

React

import React from 'react';
import { SentifydBot } from 'sentifyd-bot/react';

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

export default App;

The React wrapper also supports the onError, onOpen, and onClose callbacks.

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 = 'your-avatar-id';

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

Next.js

The component renders a 3D scene and accesses browser APIs, so it must be loaded client-side only:

'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="your-avatar-id"
        toggler={true}
      />
    </main>
  );
}

Vanilla JavaScript

import { createSentifydBot } from 'sentifyd-bot';

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

Configuration

Required props

• apiKey (string): Your avatar's API key

• avatarId (string): The avatar ID to use

Common optional props

• toggler (boolean, default true): Show the floating toggler widget; set false to render embedded

• compact (boolean, default false): Compact layout without header/footer

• overlay (boolean, sentifyd-realtime only): Frameless, transparent overlay mode sized by your own CSS

• brandName / brandLogo (string): Branding shown in the widget header

• termsHref / privacyHref (string): Links to your terms and privacy pages

• enableCaptions (boolean): Show live captions

The full attribute surface of the underlying web components (UI language, sizing, barge-in, consent injection, etc.) is documented in the Avatar Web Components Reference.

Styling

Customize the widget with CSS custom properties:

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

TypeScript Support

Both packages ship full TypeScript definitions:

import type { SentifydBotConfig, SentifydStorage } from 'sentifyd-bot';

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

API Reference

• registerSentifydBot() — Registers the web component globally. Call once before using the <sentifyd-bot> element (e.g., in Vue or vanilla setups).

• createSentifydBot(config) — Programmatically creates and mounts a bot instance. Returns the HTMLElement.

• initializeStorage(storage) — Configures a custom storage adapter (getItem / setItem / removeItem) for mobile apps or special environments.

For sentifyd-realtime, the equivalents are registerSentifydRealtime() and createSentifydRealtime(config).