Avatar Web Components Reference

Guidance on how to use the attributes of the <sentifyd-bot> and <sentifyd-realtime> web components.

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.

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.

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.

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.

Example:

Deployed avatar with widget toggler set to true.

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

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:

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

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.

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:

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