# 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 its 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.

## 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.
* canvas-width: Set the avatar canvas width in pixels. If not set, the width will fill the parent element, or a maximum default width.&#x20;
* canvas-height: Set the avatar canvas height. If not set, the height will fill the parent element, or a maximum default height.&#x20;

<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.&#x20;

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

## 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`&#x20;
  * 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%`). Set the radius of the curved corners. Use 0 value 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 `false`. 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).

## Inject End User Information and Consent

If the end user name and given consent are known in your main app, you can inject this information in the avatar.&#x20;

* **`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-acceptd`**: `true` or `false`, indicating whether the user has accepted the terms of service. If this is not true, the component will request consent from the user.