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

# Avatar Web Components  Reference

## Avatar Web Components Reference

### Introduction

The `<sentifyd-bot>` and `<sentifyd-realtime>` web components allow you to easily add a Sentifyd.io 3D conversational avatar to your web page. These components are designed for simplicity, enabling quick integration with a variety of customization options through their attributes. For a quick start guide, refer to our Integration Quick Start Guide.

Use `<sentifyd-bot>` for standard voice avatars and `<sentifyd-realtime>` for real-time (speech-to-speech) avatars. This setting is selected when the avatar is created in the sentifyd.io platform.

{% hint style="warning" %}
**One avatar per page.** Place exactly one Sentifyd component on a page. Two components on the same page — whether two of the same kind or one `<sentifyd-bot>` and one `<sentifyd-realtime>` — are not supported and will cause failures.
{% endhint %}

### What is a Web Component?

A web component is a custom HTML element that behaves similarly to standard HTML elements. It can have attributes, methods, and events, allowing developers to use it without needing to know the underlying complexities. The `<sentifyd-bot>` component is built using these principles, making it as intuitive to use as any native HTML element. To learn more about web components, visit [webcomponents.org](https://www.webcomponents.org/).

### Avatar Deployment Settings

The following attributes control how the avatar is deployed on your web page:

* **toggler**: `true` or `false`, defaults to `true`. This attribute enables the widget toggler mode, positioning the avatar widget at the bottom right of the page. When `true`, the avatar can be minimized or expanded by the user.
* **compact**: `true` or `false`, defaults to `false`. When `true`, the avatar is displayed without the header or footer, making it more compact and less intrusive.
* **overlay**: `true` or `false`, defaults to `false`. For `<sentifyd-realtime>` only. When `true`, the avatar is displayed overlaid on top of other page content. The avatar widget is transparent and displays only the voice controls button bar. Combined with `toggler`, the floating popup itself becomes the frameless overlay; standalone, the overlay fills its host element and is sized entirely by your own CSS.
* **canvas-width**: Set the avatar canvas width in pixels. If not set, the width will fill the parent element, or a maximum default width.
* **canvas-height**: Set the avatar canvas height. If not set, the height will fill the parent element, or a maximum default height.
* **chatbot-height**: Set the overall widget height in pixels (avatar canvas plus header, footer, and conversation area). If not set, it is derived from the canvas height. Use this when you need the whole widget to fit an exact space.
* **target-app**: `web` (default) or `mobile`. Use `mobile` only when embedding inside a native mobile app WebView — the widget then fills the entire screen.

On small screens, the toggler widget automatically expands to full screen regardless of the sizing attributes.

<table data-header-hidden><thead><tr><th>Compact mode (true)</th><th>Compact mode (false)</th><th data-hidden></th></tr></thead><tbody><tr><td><img src="https://2385267486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZjk54Si93aElvYoJGdG%2Fuploads%2FqseoQVE3LgQjIEIy4FHl%2Fimage.png?alt=media&#x26;token=ffeb64ae-afe3-424b-a2cd-2919e84b1333" alt="" data-size="original"></td><td><img src="https://2385267486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZjk54Si93aElvYoJGdG%2Fuploads%2Fc4yxmfecd2Pr40fvwvqC%2Fimage.png?alt=media&#x26;token=0bab2bd7-ca86-4f3f-945b-aa0482a53961" alt="" data-size="original"></td><td></td></tr></tbody></table>

***Example*****:**

Deployed avatar with widget toggler set to true.

```html
<sentifyd-bot toggler compact="false"></sentifyd-bot>
```

<figure><img src="https://2385267486-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBZjk54Si93aElvYoJGdG%2Fuploads%2F19ZwMe8B2r9B4cAD7YrS%2Fimage.png?alt=media&#x26;token=bfc67495-72ed-43ac-8317-7b70551bbfe8" alt=""><figcaption></figcaption></figure>

### Avatar Access

To connect the web component to a specific avatar you’ve created and trained on Sentifyd, use these attributes:

* **`api-key`**: This is the unique key that allows access to your avatar. Obtain the API key from the avatar's page under "Actions" > "Access API key & Domain".
* **`avatar-id`**: The unique identifier of the avatar you wish to display. This ID is available under "Actions" > "Details" on the avatar's page.
* **`token-endpoint`**: A backend endpoint URL that the component uses to obtain temporary access tokens. This enhances security by reducing direct exposure of your API key.

***Example***:

```html
<sentifyd-bot api-key="your-avatar-api-key" avatar-id="your-avatar-id" token-endpoint="https://your-backend.com/token"></sentifyd-bot>
```

{% hint style="info" %}
Legacy underscore attribute names (e.g., `api_key`, `avatar_id`, `token_endpoint`) are still accepted for backward compatibility, but use the kebab-case names in new code.
{% endhint %}

### Widget Brand Customization

Customize the avatar widget to match your brand identity using the following settings:

* **`ui-language`:** Set to one of the following supported languages:
  * English (default): `en`
  * French: `fr`
  * German: `de`
  * Spanish: `es`
  * Chinese (Simplified): `zh`
  * Arabic: `ar`
* **`terms-href`**: The URL to your terms of service. If not specified, it defaults to Sentifyd's terms at `sentifyd.io/terms`.
* **`privacy-href`**: The URL to your privacy policy. If not specified, it defaults to Sentifyd's privacy policy at `sentifyd.io/privacy`.
* **`brand-name`**: The name of your brand or institution, displayed in the avatar's interface.
* **`brand-logo`**: The URL of the logo image displayed in the avatar's header.
* **`avatar-background`**: Background behind the avatar’s transparent canvas. Enter a CSS color or gradient string. Defaults to "" (white background). Values are validated; unsupported inputs are ignored.
* **`corner-radius`**: CSS length (e.g., `12`, `12px`, `0.75rem`, `8%`). Sets the radius of the curved corners. Use a value of 0 to remove the curved corners. By default, the corners are curved 15px.

**Theme colors**

To further customize the appearance, set the values of the following CSS variables for the sentifyd-bot element:

```html
<style>
  sentifyd-bot {
    --primary-color: <valid CSS color>;
    --secondary-color: <valid CSS color>;
    --text-color-primary-bg: <valid CSS color>;
    --text-color-secondary-bg: <valid CSS color>; 
  }
</style>
```

### Configure Avatar Conversation Features

Enable or disable specific features of the avatar to suit your needs:

* **`enable-captions`**: `true` or `false`, defaults to `true`. When `true`, captions for the avatar’s and user's speech are shown.
* **`barge-in`**: `true` or `false`, defaults to `false`. When `true`, enables voice barge-in (interrupt speaking by talking).

### Realtime-Only Attributes

These attributes are accepted only by `<sentifyd-realtime>`; they have no effect on `<sentifyd-bot>`:

* **`overlay`**: See [Avatar Deployment Settings](#avatar-deployment-settings) above.
* **`webrtc-playback-mode`**: `native` (default) or `graph`. Controls how the avatar's voice audio is played back. Keep the default `native` — it is the most robust and survives interruptions like screen recorders or headphone switches. Use `graph` only if instructed for specific audio-processing scenarios.

### Inject End User Information and Consent

If the end user's name and given consent are known in your main app, you can inject this information into the avatar.

* **`username`**: A string that identifies the user, allowing for personalized interactions.
* **`email`**: The user’s email address, which can be used for contact purposes.
* **`terms-accepted`**: `true` or `false`. Default is `false`. When `true`, the deployer attests that the end user has already been informed they are interacting with an AI and has consented (EU AI Act Art. 50) in the host context. When `true`, the in-widget "Consent for AI conversation" dialog is skipped and the deployer takes responsibility for that disclosure + consent.