> For the complete documentation index, see [llms.txt](https://docs.sentifyd.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sentifyd.io/sentifyd-avatars-installation/integrating-via-npm.md).

# 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](https://www.npmjs.com/package/sentifyd-bot)           | Standard voices              | `<sentifyd-bot>`      |
| [sentifyd-realtime](https://www.npmjs.com/package/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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

### Installation

```bash
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`:

```javascript
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

```jsx
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

```vue
<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**:

```jsx
'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

```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](/manual-web-integration/avatar-web-components-reference.md).

### Styling

Customize the widget with CSS custom properties:

```css
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:

```typescript
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)`.