# Welcome ## Welcome Welcome to the official documentation for [**Sentifyd**](https://sentifyd.io)! This is your go-to resource for everything you need to know about creating, customizing, and deploying interactive AI avatars using our platform. #### What is Sentifyd? [Sentifyd](https://sentifyd.io) is an innovative platform that allows you to design and integrate interactive AI avatars with conversational and agentic capabilities into your websites. Whether you're looking to enhance customer engagement, provide virtual assistance, or simply add a dynamic element to your digital presence, Sentifyd makes it easy and intuitive. #### What Can You Do Here? * **Learn the Basics**: Get started with our Quick Start Guide, where you'll find everything you need to create your first AI avatar. * **Explore Features**: Dive into the rich set of features available on Sentifyd, including avatar customization, AI training, and multi-platform integration. * **Access Installation Guides**: Find detailed documentation on how to install and integrate your avatars into various platforms, including web and mobile. #### Why Sentifyd? With Sentifyd, you're not just creating a chatbot; you're crafting a personalized, interactive experience that resonates with your audience. Our platform leverages cutting-edge AI and avatar technology to bring your digital interactions to life. # Sentifyd AI Avatars Overview Introduction to Sentifyd AI avatars and their conversational and agentic capabilities ## Sentifyd AI Avatars Overview Sentifyd empowers you to deploy intelligent, real-time **AI avatars**—fully animated avatars capable of natural, voice-driven conversations. Most users start by adding Sentifyd as a **24/7 sales & support assistant on their website**. In that role, the agent can greet visitors, answer product and shipping questions, and even trigger store or CRM actions via tools. At the same time, Sentifyd remains a **general-purpose platform** for any web or app experience that needs an embodied AI front-end: internal tools, support portals, learning environments, digital twins, and more. With Sentifyd, your AI agentic avatars can: * Understand and respond to user input in real time using natural voice and language. * Express themselves through lifelike gestures, movement, and tone for an immersive user experience. * Access and reason over your own content—such as manuals, FAQs, product pages, or internal documents—while maintaining strict privacy and security protocols. * Connect with powerful tools such as **Model Context Protocol (MCP) servers** and other APIs, enabling task execution and contextual awareness (for example, on WooCommerce: product search, order lookup, or lead capture). These agents can be easily embedded into your website or application, offering users a compelling, intelligent interface that feels truly alive—whether you run a WooCommerce store, a WordPress site, or a custom web app. *** #### Common Use Cases While Sentifyd is flexible, a few patterns come up frequently: * **Concierges for Events, Hotels, and Tourism**\ AI-powered concierges that guide visitors to the right places, provide accurate and reliable information, and handle the majority of visitor inquiries—freeing your human staff to focus on complex cases that require a personal touch. * **E-commerce Stores**\ AI “sales reps” that guide shoppers to the right products, answer sizing and shipping questions, and handle “Where is my order?” requests. * **Customer Support & Help Centers**\ Frontline agents that resolve common issues using your knowledge base and escalate complex cases via support tickets. * **Product Tours & Onboarding**\ Embedded guides that explain complex SaaS products, walk users through flows, and answer “how do I…?” questions in context. * **Digital Twins & Brand Ambassadors**\ Personal or brand avatars that present information, answer questions, and route visitors to the right next step (booking, signup, purchase, etc.). The rest of this page describes the core capabilities that power all of these use cases. *** ### Core Capabilities #### 1. Expressive & Adaptive AI Personalities **Embodied Communication**\ Sentifyd interactive AI avatars communicate not just with words, but with presence. Each agent mirrors human behavior through natural body language—nodding, gesturing, and mood-aware animations that convey emotions like curiosity, empathy, or excitement. Realistic facial expressions enhance every interaction, making conversations feel intuitive and emotionally resonant. **Voice + Personality Fusion**\ Select from a diverse set of multilingual voices to match your audience. Go further by training each agent’s voice and personality to align with your brand—whether warm and approachable, sharp and professional, or lively and fun. **Contextually Intelligent Responses**\ Every agent is powered by Retrieval-Augmented Generation (RAG), enabling accurate, context-aware replies grounded in your documents, policies, manuals, or any custom knowledge base. This dramatically reduces hallucinations and ensures reliable, high-quality answers. *** #### 2. Real-Time Interaction **Flexible Interaction Modes**\ Instantly switch between modes based on your user’s needs: * **Avatar Mode**: Engage through a fully animated AI avatar with synchronized lip movements and a realistic neural voice. Barge-in mode can be enabled to allow natural conversations. * **Chat Mode**: Prefer a simpler interface? Switch to streamlined text-based interactions without the animated avatar. **Full Command & Customization**\ Control your AI agent effortlessly using voice or text commands. Dynamically: * Adjust the camera view (full-body, upper-body, or head-only) * Toggle captions on or off * End or restart conversations * Seamlessly switch between interaction modes at any time Sentifyd gives you the power to create fluid, adaptive experiences that fit any environment—whether embedded on a website or integrated into an app. *** #### 3. Privacy-First Design **Zero Data Retention by Default**\ Sentifyd is built with user privacy at its core. No conversation transcripts or logs are stored on Sentifyd's servers. We only keep the conversation hot for a couple of hours for context management and easier resuming. Our industry-trusted suppliers of LLM models may also keep the conversations for a short period for legal purposes. We do not train our models or application using your data.\ End users retain full ownership of their data and can download their conversation transcript during a conversation. User personal data might be collected with their consent during a conversation to perform tasks such as sending customer support requests. **Built-In Safety & Compliance**\ Sentifyd agents operate within secure, AI-guarded environments. Through integrations with leading AI platforms, all interactions are protected by advanced safety mechanisms. Harmful, unsafe, or non-compliant prompts are proactively detected and blocked, ensuring every conversation stays within ethical and legal boundaries. *** #### 4. Customizable Engagement **Create an Avatar**\ Start by designing your AI agent’s appearance using available avatar options. You can optionally use **Avaturn** for a realistic avatar based on your photos. **Infuse Personality & Intelligence**\ Upload your own content—such as product manuals, policies, FAQs, or internal docs—to build a custom knowledge base that powers accurate, context-aware responses.\ Define persona traits, preferred tone, and sample dialogues to shape how your agent thinks, speaks, and interacts—whether professional, playful, empathetic, or anything in between. **Customizable Avatar Widget**\ Customize the avatar widget to match your brand, set the widget interface language to one of six supported languages, and adapt how the widget is installed on your website. You can also change the colors, logo, add a company name, and other styling & branding options. Please check the installation guides. Your AI agent doesn’t just look the part—it *acts* the part, fully aligned with your brand identity and user needs. *** #### **5. Advanced Tools** **Equip Your Avatar with Powerful Tools** Give your AI agentic avatar more than just a voice—give it the ability to act. Sentifyd avatars can be connected to **custom tools** that extend their functionality, allowing them to solve real problems, fetch live information, and even interact with external systems on your behalf. **Out-of-the-Box Tools:** * **Tools to control the avatar itself and the chatbot user interface** * **Web Search**\ Agents can safely browse the internet in real time to provide up-to-date answers, going beyond your internal data sources when needed. * **Send Support Requests**\ When a user needs human help, the agent will collect contact information (e.g., name, email, phone) and instantly submit a support request to your team—ensuring seamless escalation. *** **Connect Custom Tools with MCP Servers** For advanced integrations, Sentifyd supports **MCP (Model Context Protocol) tools**, allowing your agent to interface with any backend service or external API in real time. **What MCP Tools Enable:** * Execute actions directly from within a conversation * Get live responses from custom services (e.g., booking systems, internal APIs, IoT devices, CRMs) * Use custom headers and secure tokens to authenticate connections to MCP servers. **MCP Tool Configuration Includes:** * **Connection Type**: Streamable HTTP or SSE * **Endpoint URL**: Your custom API or service endpoint * **Headers (JSON)**: Securely pass tokens or metadata (e.g., `{"Authorization": "Bearer TOKEN"}`) With MCP servers, your AI agents become fully **agentic**—capable not just of understanding but of **doing**. Automate tasks, connect with live systems, and give your users real results in the flow of conversation. *** ### How It Works: User Experience 1. **Engage the Agent**\ Users begin by clicking or tapping to activate your AI agent—instantly met with a lifelike, responsive avatar ready to assist. 2. **Speak or Type Naturally**\ Whether through voice or text, users can ask questions, give commands, or hold a conversation just like they would with a real person. 3. **See the Agent in Action**\ The agent responds in real time, using voice, gestures, facial expressions, and live captions. It can also perform actions—like retrieving data, searching the web, or submitting a support request—based on the conversation. 4. **Adjust the Experience**\ Users can switch between avatar and chat-only modes, toggle captions, and adjust the avatar's view (head-only, upper-body, or full-body) for their preferred experience. 5. **Wrap Up & Retain the Conversation**\ At any point, users can end the conversation. If enabled, they may also download a transcript of the interaction for their records. # Choosing a Voice Mode Every Sentifyd avatar has a **voice mode**, chosen when you create the avatar. It determines how the avatar listens and speaks, which voices are available, and which installation component your website uses. This page helps you pick the right mode for your use case. ### The Two Modes at a Glance | | **Standard** | **Real-time** | | ---------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Conversation style | Turn-based: the user speaks or types, then the avatar replies | Fluid speech-to-speech, like a phone call | | Latency | Noticeable pause before replies | Low — near-instant responses | | Voice selection | Large catalog of natural, region-specific voices | Smaller set of voices | | Languages | Choose a language, or Multilingual with up to four locales | Inherently multilingual — understands and answers in the user's language; your selected language is the default | | Barge-in (interrupting the avatar by speaking) | Optional | Optional, and feels most natural here | | Overlay display mode | — | Available — frameless avatar layered over your own background | | Web component / npm package | `` / `sentifyd-bot` | `` / `sentifyd-realtime` | | Network | Standard HTTPS/WebSocket | Also uses WebRTC audio streaming | ### Which Should You Choose? **Choose Standard if…** * Voice identity matters most: you want a specific accent, age, or tone from the large voice catalog. * Your users mostly **type** (chat mode) or the conversation is naturally turn-based (FAQ answering, guided forms). * Your audience may be on restrictive corporate networks where WebRTC can be blocked. **Choose Real-time if…** * You want the most natural, lifelike conversation — users talking to the avatar the way they'd talk to a person. * Low latency matters: receptions, kiosks, concierges, sales conversations. * You want to serve visitors in many languages without configuring each one. * You want the **Overlay** display mode to blend the avatar into a hero section or custom design. ### Where You Set It Voice mode is selected in the **Basic Information** step of the avatar creation form, together with the language and voice (the voice list changes depending on the mode). See [Creating Avatars](/features/editor). You can change an avatar's voice mode later by editing the avatar — the change takes effect on the next conversation. {% hint style="warning" %} The voice mode determines the integration component. If you change the mode of an avatar that is already deployed, update your embed accordingly: `` for Standard, `` for Real-time. The shareable hosted link and the WordPress plugin (with the matching voice-mode option selected) handle this for you. {% endhint %} # Creating Avatars Step-by-step guide to creating and customizing your avatars. ## Creating Avatars Welcome to the avatar creation guide for Sentifyd! In this guide, you'll learn how to create an avatar. ### Supported Avatars Sentifyd offers a set of ready-made, stylized, professional 3D avatars with various appearances, clothing, and accessories. Here is a sample of the available avatars. More avatar options are available.
In addition, Sentifyd enables you to bring your own [**Avaturn**](https://avaturn.me) **realistic avatars.** Avaturn avatars are designed for users seeking realistic, lifelike avatars that closely resemble real human features. This option provides photo-realistic, lifelike avatars with premium-quality speech and natural expressions.
### Step-by-Step Guide to Creating and Customizing Your Avatar Click the **Create an Avatar** button to begin the process. You can find the button in the Platform menu after you have logged in to your account. The avatar creation form will guide you through three simple steps to create and train your avatar.
#### Basic Information Before diving into the design process, you'll start by setting up some basic information: * **Avatar Name**: Assign a name to your avatar. * **Voice mode:** Select the voice mode. Standard voices have more latency, but provide a larger selection of voices. Real-time mode provides a real-time, low-latency speech-to-speech experience, but with a limited number of voices. See [Choosing a Voice Mode](/features/choosing-a-voice-mode) for a full comparison. * **Language**: Choose the language for your avatar. To use multiple languages, select "Multilingual" in the Language field, then pick up to four languages in the Multilingual Locales section. Real-time voice mode has inherent multi-language capability even if you select a single language. The single selected language will be the default and preferred one. * **Voice**: The available voice options depend on the voice mode and selected language, offering natural and region-specific voices. Test the voices by clicking the play icon. #### Avatar Creator Go to the second step of the avatar creation form, and select the avatar type. You have two options for 3D avatars: 1. **Readymade 3D Avatars:** Select one of the available stylized 3D avatars from our library. 2. **Custom Avaturn Realistic Avatars:** For a more lifelike avatar, use **Avaturn** to create a realistic 3D model. This platform specializes in generating avatars with detailed facial features, skin textures, and realistic proportions. > Note: You need to sign up with Avaturn first to create Avaturn realistic avatars. * **Avaturn Avatar Creation Guide:** * **Design Your Avatar** * Utilize the QR code for easy photo integration via mobile. * Customize details like skin tone, facial structure, and expressions. * **Ideal Use** * Perfect for crafting avatars that mirror real individuals or brand representatives. * **Save and Update** * Click 'Next' once completed to save your design. * Your avatar's details will auto-update on the Sentifyd platform. #### Choose Avatar Training Option and Submit After designing your avatar, choose one of the following training options: * **Create a new training from scratch**: Create a new training record for your avatar. This choice will guide you to the empty Avatar Training form. See the [Training Avatars](/features/markdown) documentation. * **Assign One Of Your Trainings**: Reuse trainings from previous avatars if applicable. * **Start training from a template**: Utilize pre-existing templates from our library for common scenarios, streamlining the training process. This option will clone a template training and use it as a starting point. * **No Training:** Choose this to create the avatar and assign training later. Once you’ve finished, review all settings to ensure everything is configured correctly. When you’re satisfied, submit your avatar. You will be redirected to the next step. # Training Avatars Learn How to Create Effective Trainings for Your Speaking Avatars. ## Training Avatars ### Overview In Sentifyd, our training is highly adaptable. You can assign and reassign training to any avatar without dependence on a specific avatar. Start with our pre-made templates or design your own training program from scratch. ### Creating a Training Creating training for your avatar involves three main steps, each of which is managed through different tabs in the training form. #### **1. Persona Tab** In this tab, you'll define the persona of your avatar. This step is crucial as it sets the tone and character of the avatar's responses. * **Training Name**: Give your training a meaningful name for easy identification. * **Response Length**: Restrict the response length by specifying a maximum word count. * **Style**: Choose from various styles such as creative, formal, friendly, or funny, depending on the desired personality of the avatar. * **Persona Role**: Define the role of the avatar (e.g., Customer Support, Virtual Salesperson). * **Persona Description**: Provide a detailed description of the persona to guide the AI in generating appropriate responses. * **Conversation Examples:** Provide up to 25 Q\&A examples the avatar should always answer from directly. These are injected into the system prompt, so they ground the avatar's behavior without needing a knowledge-base lookup — ideal for persona details, canned responses, preferred phrasings, and short factual answers. {% hint style="info" %} **CSV Upload Guidelines**: When uploading a CSV, make sure it adheres to the specified format, with distinct columns for user inputs and AI responses. {% endhint %} #### **2. Knowledge Sources Tab** This tab is where you provide sources such as documents or a website address to enable the chatbot to respond based on your sources. The sources ground the chatbot and enable it to provide specific answers based on your needs. * **Documents:** You may upload up to five documents in the following formats: PDF, Word, Excel, PowerPoint, Text, or HTML. Each document can be a maximum of 16 MB. * **Website URL:** Enter a publicly accessible website URL. The website content is extracted and indexed for the avatar. You can re-index the URL at any time to refresh the content. **How website indexing works:** * Starting from the URL you provide, Sentifyd follows links within the same site up to **3 levels deep** and indexes up to roughly **150 pages**, using your site's sitemap when available to pick the most relevant pages. * Only publicly accessible pages are indexed — pages behind logins or paywalls are not. * Indexing is a **snapshot**: when your website content changes, re-index the URL from the training page to refresh the avatar's knowledge. * For large sites, point the avatar at the most relevant section (e.g., `https://example.com/help`) rather than the homepage, so the page budget is spent on content that answers your users' questions. #### **3. Tools Tab** The **Tools Tab** allows you to extend your AI agent’s capabilities by enabling additional tools it can use during live conversations. Tools enhance your agent’s functionality—allowing it to perform searches, send data, and even interface with your own systems in real time. **✅ Always-Enabled Tools** These tools are built-in and cannot be disabled, as they form the foundation of Sentifyd’s interactive experience: * **Control 3D Avatar**\ Allows the agent to animate and control the 3D avatar—managing gestures, facial expressions, posture, and avatar view (e.g., full-body or head-only). * **Control Sentifyd Widget**\ Enables the agent to manipulate elements of the chat interface—such as toggling captions, switching between voice and text modes, and ending or restarting conversations. *** **🌐 Web Search Tool** Allow your agent to safely access real-time web information. This tool enables the avatar to perform controlled web searches, expanding its ability to answer questions beyond your internal data sources. *** **📩 Send Support Request Tool** When the agent can’t resolve a user’s issue, this tool enables it to escalate gracefully. It will: * Prompt the user for contact details (email and phone) * Automatically send a support request to your predefined support email **Setup required**: You must provide a support email address in the configuration. *** **⚙️ MCP Tools – Custom Backend Integrations** MCP (Model Context Protocol) tools allow your agent to securely interact with your own APIs, systems, or services. Perfect for advanced workflows, these tools enable your agent to: * Send and receive data via HTTP or SSE connections * Execute real-time API calls (e.g., to booking systems, internal dashboards, or CRMs) * Stream live updates into the chat or avatar response **Configuration options:** * **Connection Type**: Streamable HTTP or Server-Sent Events (SSE) * **Endpoint URL**: Your service URL * **Headers (JSON)**: Optionally, add custom request headers (e.g., `{"Authorization": "Bearer TOKEN"}`) {% hint style="info" %} You don't need to build anything to use MCP tools — no-code platforms like Zapier can host them for you. See [Adding MCP Tools to Your Avatar](/features/adding-mcp-tools-to-your-avatar) for setup options, from no-code to custom servers. {% endhint %} #### Submitting the Training Fill out the forms and review your inputs to ensure accuracy. When ready, submit your training for processing. It may take several minutes to fully index and process. Check the training page to monitor the indexing status. # Adding MCP Tools to Your Avatar MCP tools let your avatar **act**, not just talk: book appointments, look up orders, capture leads in your CRM, check availability, and more. Your avatar connects to one or more **MCP servers** — services that expose actions through the open [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) standard — and the AI agent calls those actions in real time during a conversation. The good news: **you don't need to develop anything to get started.** There are three ways to get an MCP server, from no-code to fully custom. *** ### Option 1 — Use an MCP Platform like Zapier (no code) MCP platforms let you turn everyday business actions into avatar tools in minutes. For example, with [Zapier MCP](https://zapier.com/mcp) you can expose actions from thousands of connected apps — book a meeting in Google Calendar or Calendly, add a lead to HubSpot, append a row to a spreadsheet, send a Slack message — without writing any code: 1. Create an MCP server on the platform and pick the specific actions you want your avatar to perform. 2. Copy the server's **endpoint URL** and its **authentication header**. 3. In your avatar's training (Tools tab), add an MCP tool entry with that URL and header. See [Training Avatars](/features/markdown). 4. Save, then test by asking the avatar to perform the task (e.g., “Can you book me an appointment for Thursday?”). Other MCP platforms and automation services offer similar hosted MCP servers — the same steps apply: get a URL and credentials from the platform, paste them into Sentifyd. {% hint style="success" %} **Tip:** Expose only the few actions your avatar actually needs. A short, focused list of clearly named actions makes the agent far more reliable than dozens of loosely related ones. {% endhint %} ### Option 2 — Use a Ready-Made MCP Server from Your Vendor More and more SaaS products — booking systems, e-commerce platforms, help desks — ship their own MCP endpoints. If a system you already use offers one, ask your vendor for the MCP endpoint URL and an API token, and connect it the same way. ### Option 3 — Build Your Own MCP Server (advanced) For full control — custom business logic, direct database lookups, internal APIs — you (or your developer) can build a custom MCP server. The rest of this page covers what you need to know. *** ### How the Connection Works 1. You add an MCP tool entry to your avatar's training (Tools tab): a **name**, a **connection type**, the server's **endpoint URL**, and optional **headers**. 2. When a conversation starts, Sentifyd connects to the MCP server, discovers the tools it exposes, and makes them available to the AI agent alongside the built-in tools. 3. When the user asks for something a tool can do, the agent calls it, waits for the response, and weaves the result into its spoken or written reply. {% hint style="info" %} The connection is made **from Sentifyd's servers** — the user's browser never talks to your MCP server, and your endpoint URL and headers are never exposed to end users. {% endhint %} ### Server Requirements * **Transport**: Streamable HTTP (recommended) or SSE (legacy). Hosted platforms like Zapier use Streamable HTTP. * **Reachability**: The endpoint URL must be **publicly reachable**. For security, URLs that point to private or local addresses (e.g., `localhost`, LAN IPs) are rejected. Use HTTPS in production. * **Startup speed**: The server must respond to the initial connection and tool listing within a few seconds. If it doesn't, its tools are skipped for that conversation — the avatar still works, just without those tools. * **Tool call speed**: Aim for tool responses well under 5 seconds — the user is waiting in a live voice conversation. Calls that take longer than about 30 seconds are abandoned. ### Authentication Use the **Headers (JSON)** field to pass credentials with every request Sentifyd makes to the server: ```json { "Authorization": "Bearer YOUR-SECRET-TOKEN" } ``` A custom MCP server should validate the token and reject unauthenticated requests — the endpoint is on the public internet. Your credentials are kept confidential by Sentifyd. ### Tool Naming * Tool names exposed by the server are automatically **prefixed with the tool entry's name** you configured in Sentifyd, so tools from multiple servers can't clash. * Keep tool names short, lowercase, and descriptive, using only letters, digits, `_`, `.`, or `-` — e.g., `get_order_status`, `book_table`. ### Designing Tools for Voice Conversations The agent decides when to call your tools based on their names and descriptions, so treat those as part of your prompt engineering: * **Write clear descriptions.** Describe exactly what each tool does, when to use it, and what each parameter means. This is the single biggest factor in whether the agent uses your tool correctly. * **Expose few, focused tools.** A handful of well-described tools outperforms dozens of overlapping ones. * **Return concise results.** The response is fed to a language model and often spoken aloud. Return short, structured text or compact JSON — not full HTML pages or large payloads. * **Be fast.** Every second of tool latency is a second of silence for the user. * **Fail gracefully.** Return a clear, human-readable error message (e.g., "Order 1234 was not found") rather than a technical error. Error messages are passed back to the agent, so a good one lets the avatar explain the problem and try again. ### Minimal Custom Server Example (Python + FastMCP) ```python # pip install fastmcp from fastmcp import FastMCP mcp = FastMCP("orders") @mcp.tool def get_order_status(order_id: str) -> str: """Look up the shipping status of a customer order by its order number.""" # Replace with a real lookup against your database or API return f"Order {order_id} shipped on July 3 and arrives Thursday." if __name__ == "__main__": # Serves the MCP endpoint over Streamable HTTP mcp.run(transport="http", host="0.0.0.0", port=8000) ``` Deploy it behind HTTPS (e.g., `https://tools.example.com/mcp`), then configure the tool in Sentifyd: * **Name**: `orders` * **Connection Type**: Streamable HTTP * **Endpoint URL**: `https://tools.example.com/mcp` * **Headers (JSON)**: `{ "Authorization": "Bearer YOUR-SECRET-TOKEN" }` ### Testing & Troubleshooting * For custom servers, test first with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) (`npx @modelcontextprotocol/inspector`) to confirm the tool list and calls work before wiring it to Sentifyd. * After saving the training, start a conversation and ask a question that should trigger the tool. * **Tools not being used?** Check that the endpoint is publicly reachable (not a private/localhost address), responds quickly to the initial connection, and that the tool descriptions clearly match the kinds of questions you're asking. * If one MCP server is down, other configured MCP servers and built-in tools continue to work — failures don't spread. # Customizing Avatar Widgets ## Customizing Avatar Widgets On the avatar page you can customize the behaviors, layout, branding, and visual styling of the avatar widget. The widget preview on the left reflects the changes you make, showing how the widget will look when eventually deployed to a website.
SettingExplanation
Display mode

Controls how the avatar widget is presented on your page. Choose one of four layouts:

  • Embedded — full panel rendered inline within the page;
  • Compact — smaller embedded panel that takes less vertical/horizontal space;
  • Toggler — a floating chat-bubble button in the corner that opens the avatar on click (good for site-wide assistants);
  • Overlay (realtime avatars only) — frameless, transparent rendering that fills its host element with no header/footer chrome, so you can layer the avatar over a hero image, video, or any background and size it entirely with your own CSS.
CaptionsWhen enabled, on-screen text captions are shown for the avatar's spoken responses. Improves accessibility and lets users follow along in noisy environments or when audio is muted.
Barge-inWhen enabled, the user can interrupt the avatar mid-sentence simply by speaking — the avatar stops talking and starts listening. When disabled, the user must wait for the avatar to finish before speaking.
UI languageSets the language of the widget's interface text (buttons, tooltips, status messages, captions UI). Supported: English, French, German, Spanish, Chinese (Simplified), and Arabic. Independent of the conversation language, which is handled by the underlying AI model.
Brand nameOptional brand or company name shown in the widget header. Helps reinforce your identity when the avatar is embedded on a third-party site or shared publicly.
Brand logo URLDirect URL to a logo image (PNG/SVG/JPG) displayed in the widget header alongside the brand name. Use HTTPS and an image hosted on a domain that allows hot-linking.
Avatar backgroundBackground applied behind the 3D avatar canvas. Accepts any valid CSS background value — a solid color (#0a0a0a), a gradient (linear-gradient(...)), or an image URL (url(...)). Leave blank for the default transparent/neutral background.
Corner radiusBorder radius (in pixels) for the widget's outer container, controlling how rounded its corners are. 0 = sharp corners; higher values = more rounded. Ignored in Overlay mode (which has no chrome).
Theme colorsFour customizable CSS color variables that drive the widget's look: Primary color (main accent — buttons, highlights), Secondary color (supporting accent), Text on primary background, and Text on secondary background. Pick contrasting text colors to keep labels legible against your chosen primary/secondary.
Terms of service and privacy policy linksURLs shown in the widget footer linking to your Terms and Privacy pages. Required for compliance when collecting user input or voice data; defaults to Sentifyd's own policies if left blank.
Sizing optionsPixel dimensions for the widget: Canvas width and Canvas height size the avatar (3D scene) area; Chatbot height sets the conversation/transcript panel height. These apply in Embedded, Compact, and Toggler modes (in Toggler mode on small screens the widget expands to full screen regardless). They are ignored in Overlay mode, where the overlay fills its host element and is sized entirely by your own CSS.
{% hint style="info" %} Where these settings apply. The settings above are configured on the Avatar Page and saved to your avatar's profile. They are remembered the next time you open the Avatar Page and are also pre-loaded on the Deployment Page so the generated HTML embed snippet reflects them automatically. Important: these settings only take effect on customer sites that use the generated HTML embed snippet as-is. If you (or your developers) hand-author the `` / `` web component without copying the generated attributes, the saved settings are not applied — the attributes you set on the element win. WordPress deployments are a separate case: the Sentifyd Avatar WordPress plugin has its own settings panel inside the WP admin, and those plugin settings override anything configured here. To customize the widget on a WordPress site, configure it from the plugin's settings page rather than the Avatar Page. {% endhint %}
# Installing Sentifyd Avatars ## Installing Sentifyd Avatars Choose the installation approach that best matches **where** your users interact with you and **how much** control you need over look‑and‑feel. *** #### 1 — Shareable hosted link *(ready)* Sentifyd hosts a standalone web page for every avatar. Share the dedicated URL anywhere (email, socials, QR code on packaging, iframe embed) and your audience can interact immediately with your avatar. See [Shareable Avatar Link](/sentifyd-avatars-installation/shareable-avatar-link). *** #### 2 — WordPress plugin (no code) You can easily add the Sentifyd avatar to your WordPress website using the Sentifyd avatar plugin, which you can get from the WordPress plugin directory. See [Sentifyd Avatar WordPress Plugin](https://wordpress.org/plugins/sentifyd-avatar/). You'll need the following credentials to configure the WordPress plugin settings: * avatar ID * avatar API key In the plugin settings, also select the voice mode matching your avatar (standard or real-time) — the plugin embeds the right component for you. *** #### 3 — NPM package Building with React, Vue, or Node? Install our [sentifyd-bot](https://www.npmjs.com/package/sentifyd-bot) or [sentifyd-realtime](https://www.npmjs.com/package/sentifyd-realtime) package, depending on the avatar's selected [voice mode](/features/choosing-a-voice-mode), and integrate the component directly into your application. See [Integrating via NPM](/sentifyd-avatars-installation/integrating-via-npm) for setup instructions and framework examples. *** #### 4 — Manual Web integration with HTML embed *(low code)* Need finer control over styling or token handling? Our Web Component lets you embed an avatar anywhere you can run HTML/JS — with or without a backend. \ 👉 *See the* *Manual Web Integration* *chapter for full walkthroughs.* *** ### Coming Soon The following installation methods are under development. *** #### Google Tag Manager If your website(s) support Google Tag Manager (GTM), you can easily add and configure the Sentifyd Avatar using our Sentifyd Avatar GTM template. Create a new tag using our template, configure at least the avatar API key, and the avatar will be deployed on your website instantly. *** #### Shopify App Shopify merchants will soon be able to: 1. Install the **Sentifyd** app from the Shopify App Store. 2. Select or create an avatar right inside the admin UI. 3. Pick where it appears (storefront chat bubble, dedicated page, or product pages). *** #### Android Companion App Download the **Sentifyd Avatar** Android app to bring conversational avatars to kiosks, demo tablets, or trade‑show devices. * Launch the app and scan the **QR code** shown next to your avatar in the Sentifyd platform — or paste the **Avatar API Key**. * Pin the device to a stand and let visitors talk hands‑free. The app auto‑updates the avatar’s visuals and behavior whenever you publish changes. # Shareable Avatar Link The fastest way to put your avatar in front of people: Sentifyd hosts a ready-made, full-screen web page for every avatar. No installation, no code — just share the link. ### Getting the Link 1. Open your avatar's page in the Sentifyd platform. 2. Click the **Shareable Link** button. 3. Copy the link, or open it in a new tab to try it immediately. ### What Visitors Get * A clean, full-screen avatar page that works on desktop and mobile browsers. * Your saved **widget customization** (branding, colors, captions, UI language, and other settings from the Avatar Page) is applied automatically. * The page always uses the right technology for your avatar's voice mode — no configuration needed, even if you change the voice mode later. ### Ways to Use It * Send it in **email signatures**, newsletters, or support replies. * Post it on **social media** profiles and campaigns. * Turn it into a **QR code** for packaging, posters, table tents, or trade-show booths. * Embed it in an **iframe** on pages where you can't add scripts. * Load it on a tablet or kiosk browser for walk-up experiences. ### Sharing Safely {% hint style="warning" %} **Anyone with the link can chat with your avatar**, and those conversations count toward your account's usage. Share it where that's what you want (marketing, support), and keep it away from places where it could be abused. If a link needs to be retired — for example, it leaked or a campaign ended — **regenerate the avatar's API key** from the avatar page. This immediately invalidates the old link (and any embeds using the old key), and the Shareable Link button will show the new link. {% endhint %} # 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-realtime](https://www.npmjs.com/package/sentifyd-realtime) | Real-time (speech-to-speech) | `` | 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 ( console.log('Bot ready!', bot)} /> ); } export default App; ``` The React wrapper also supports the `onError`, `onOpen`, and `onClose` callbacks. #### Vue 3 ```vue ``` #### 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 (

Welcome

); } ``` #### 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). ### 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 `` 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)`. # Quick Start Guide Integrating Avatars in Websites & Apps ## Quick Start Guide ### Introduction This guide will walk you through the simple steps needed to integrate a Sentifyd 3D AI avatar into your website or web application. To begin, ensure you have the avatar's API key, which can be found in the Sentifyd platform under the avatar section. ### Preparation: Create an Avatar Before you can deploy an avatar, you need to create and train it on the Sentifyd platform. In addition, customize the avatar widget using the customization panel provided on the avatar page. Once done, open the Website Deployment modal from the avatar page.
### Step 1: Set Allowed Domain This is a required step to allow the avatar to be deployed on your website. Add your website domain and click on Save Domain.
### Step 2: Copy the Avatar Embed Use the provided embed creator to configure and copy your avatar embed. {% hint style="info" %} #### **Security Note:** Exposing your avatar API key in the frontend is generally safe. This key is public and only permits interaction with the avatar, and its usage is restricted by the “allowed domains” setting—meaning the avatar cannot be deployed on unauthorized websites. If you prefer not to expose your avatar API key at all, you can follow our Backend-for-Frontend (BFF) guide to issue short-lived access tokens instead. {% endhint %}
**Optional: Advanced customization of the Avatar** You can customize your avatar's behavior and appearance using additional attributes on the `` or `` component. For a full list of customization options, please refer to the detailed guide on the `` / `` Web Components. ### Step 3: Deploy on Your Website Next, copy and add the avatar embed code to your website wherever you want the avatar to appear. Make sure the script tag is placed in the head or at the end of the body element. If you chose the toggler option, the parent size does not matter and the avatar will be deployed floating in the page's bottom-right corner. # Avatar Web Components Reference Guidance on how to use the attributes of the \ and \ web components. ## Avatar Web Components Reference ### Introduction The `` and `` 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 `` for standard voice avatars and `` 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 `` and one `` — 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 `` 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 `` 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.
Compact mode (true)Compact mode (false)
***Example*****:** Deployed avatar with widget toggler set to true. ```html ```
### 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 ``` {% 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 ``` ### 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 ``; they have no effect on ``: * **`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. # Short-lived Avatar Tokens (Advanced) Use the Backend-for-Frontend (BFF) pattern when you want your own backend to fetch short-lived Sentifyd access tokens and hand them to the browser on demand. This keeps API keys and refresh tokens of ## Short-lived Avatar Tokens (Advanced) #### When should I use this? * You do not want to expose your Sentifyd `AVATAR_API_KEY` in JavaScript or in a static HTML file. * Your site already calls your own backend before rendering most pages (typical SSR / Next.js, Remix, Flask, Rails, etc.). * You need full control over who may request a token (e.g. only logged-in customers). If you simply need to embed a public avatar on a static site, consider the **no-backend** integration described in the *Quick Start* guide instead. #### 1 — Add an endpoint in your backend Create a lightweight route that: 1. Receives a **GET** from the browser. 2. Calls the Sentifyd Authentication API with your **`AVATAR_API_KEY`**. 3. Returns a JSON payload containing: * an `accessToken` (JWT) * a `refreshToken` * `avatarParameters` (theme, voice, etc.) **Reference endpoint implementation** {% tabs %} {% tab title="Python (Flask)" %} ```python from flask import Blueprint, current_app, jsonify, request import requests blueprint = Blueprint("sentifyd", __name__) @blueprint.route("/request_tokens", methods=["GET"]) def request_tokens(): sentifyd_backend_url = current_app.config["SENTIFYD_BACKEND"] + "/api/v1/chatbot/login" avatar_api_key = current_app.config["AVATAR_API_KEY"] payload = {"avatar_api_key": avatar_api_key} try: response = requests.post(sentifyd_backend_url, json=payload) if response.status_code != 200: return jsonify({"error": "Authentication failed", "details": response.json()}), response.status_code data = response.json()["data"] frontend_payload = { "tokens": { "accessToken": data["access_token"], "refreshToken": data["refresh_token"], }, "avatarParameters": data["avatar_params"], } return jsonify(frontend_payload), 200 except Exception as e: current_app.logger.exception("Error while requesting Sentifyd tokens") return jsonify({"error": "Internal server error"}), 500 ``` {% endtab %} {% tab title="Typescript (Express.js)" %} ```typescript import express, { Request, Response } from "express"; import axios from "axios"; const router = express.Router(); // Example configuration values (could also come from process.env) const SENTIFYD_BACKEND = process.env.SENTIFYD_BACKEND || "https://serve.sentifyd.io"; const AVATAR_API_KEY = process.env.AVATAR_API_KEY || "your-avatar-api-key-here"; router.get("/request_tokens", async (req: Request, res: Response) => { const sentifydBackendUrl = `${SENTIFYD_BACKEND}/api/v1/chatbot/login`; const payload = { avatar_api_key: AVATAR_API_KEY }; try { const response = await axios.post(sentifydBackendUrl, payload); if (response.status !== 200) { return res.status(response.status).json({ error: "Authentication failed", details: response.data, }); } const data = response.data.data; const frontendPayload = { tokens: { accessToken: data.access_token, refreshToken: data.refresh_token, }, avatarParameters: data.avatar_params, }; return res.status(200).json(frontendPayload); } catch (error: any) { console.error("Error while requesting Sentifyd tokens:", error); return res.status(500).json({ error: "Internal server error" }); } }); export default router; ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Secure config:** store `AVATAR_API_KEY` and `SENTIFYD_BACKEND` in environment variables or a secrets store—never commit them to git. {% endhint %} **Tips** * Make sure CORS allows your own origin (`Access‑Control‑Allow‑Origin`). * Add auth middleware if only signed‑in users may chat with the avatar. #### 2 — Serve the Sentifyd web component 1. Load the Sentifyd component loader **once** on every page that needs an avatar: ```html ``` 2. Place the `` element where you want the avatar to appear. Provide **both** the URL of the endpoint you just created *and* the `avatar-id` you received from the Sentifyd dashboard. ```html ``` * `token-endpoint` — full, publicly reachable URL of the route that returns the JSON payload shown above. * `avatar-id` — the unique identifier of the avatar you created in the Sentifyd console. > **Avoid duplicates:** keep each attribute only once; browsers ignore later duplicates. *** #### 3 — How it works 1. The web component boots and issues a **GET** to `token-endpoint`. 2. Your backend exchanges the `AVATAR_API_KEY` for fresh tokens. 3. The frontend receives `{ tokens, avatarParameters }` and opens a WebSocket to Sentifyd. 4. When the access token is close to expiring, the component refreshes it directly with the Sentifyd backend using the refresh token — your endpoint is not called again unless a full re-authentication is needed. *** #### 4 — Minimal example (static HTML) ```html Sentifyd BFF demo

Hello, Sentifyd!

``` # Troubleshooting & Requirements ### Browser & Device Requirements * **Browser**: A current version of Chrome, Edge, Firefox, or Safari. The 3D avatar requires **WebGL** support (available in all modern browsers unless disabled by policy or very old GPU drivers). * **HTTPS**: Microphone access requires a secure context. The page embedding the avatar must be served over **HTTPS** (or `localhost` during development). * **Audio**: Speakers/headphones for voice output; a microphone for voice input. Text chat works without either. * **Network**: Standard HTTPS/WebSocket connectivity. Real-time avatars additionally use **WebRTC**; very restrictive corporate firewalls that block WebRTC media can prevent real-time audio. {% hint style="warning" %} **One avatar per page.** Running two Sentifyd web components on the same page (two `` elements, two `` elements, or one of each) is not supported and is a common source of failures. Make sure your page — including templates, themes, and tag managers that might inject a second copy — embeds exactly one avatar. {% endhint %} *** ### The avatar doesn't appear * Confirm the **script tag** is present and loading (check the browser's Network tab): * Standard: `https://frontend.sentifyd.io/sentifyd-bot/main.js` * Real-time: `https://frontend.sentifyd.io/sentifyd-realtime/v1/main.js` * Use the component that matches the avatar's **voice mode**: `` for standard voices, `` for real-time. A mismatch will fail to connect. * Check that both `avatar-id` and either `api-key` or `token-endpoint` are set on the element. * Make sure only **one** Sentifyd component is present on the page (see the note above). * Open the browser console — the component logs descriptive errors for every failure mode below. ### Authentication errors The browser console shows the login failure reason: | Symptom / status | Cause | Fix | | ------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `Avatar not found` (404) | Wrong `avatar-id`, or the avatar was deleted | Copy the ID from the avatar page ("Actions" > "Details") | | `Unauthorized` (401) | Wrong or rotated API key, or the site's domain is not in the avatar's **allowed domains** | Verify the API key; add the exact domain in the Website Deployment modal (see the [Quick Start Guide](/manual-web-integration/quick-start-guide)) | | `Too many login attempts` (429) | Rate limiting after repeated failures | Wait a moment and retry; fix the underlying credential error | {% hint style="warning" %} The **allowed domain must match the domain the page is actually served from**. If you deploy the same embed to staging and production, add each domain. Testing from a different subdomain is a common cause of 401 errors. {% endhint %} ### No sound / avatar is silent * Browsers block audio **autoplay** until the user interacts with the page. The widget automatically unlocks audio on the first click or tap — make sure the user has interacted with the widget (this also applies after a page reload with a resumed conversation). * Check the device's output volume and that the browser tab is not muted. * On iOS, ensure the physical silent switch is off. ### Microphone problems * **Permission denied**: If the user dismissed or blocked the mic prompt, re-enable it via the browser's site settings (padlock icon in the address bar), then reload. * **No prompt at all**: The page is probably not served over HTTPS — browsers only allow microphone access on secure pages. * **Mic busy or missing**: Another application may be holding the microphone, or the operating system's microphone permission for the browser is disabled (common in macOS and Windows privacy settings). * **Echo / avatar hears itself**: Echo cancellation is enabled by default. If users are on loudspeakers in a noisy or kiosk setup, prefer headphones, or disable barge-in so the avatar doesn't listen while speaking. ### Real-time avatar issues * Real-time avatars stream audio over **WebRTC**. If audio never starts on a corporate network, ask IT whether WebRTC/UDP media is blocked. * If the session drops after being idle, simply click the widget to reconnect — idle sessions are disconnected to save resources. ### WordPress specifics * The Sentifyd Avatar WordPress plugin has its **own settings panel**, which overrides the customization saved on the Avatar Page. Configure widget appearance in the plugin settings. * Select the correct **voice mode** in the plugin settings: choose the real-time option for real-time avatars and the standard option for standard-voice avatars. The plugin embeds the matching component for you — a mismatch with the avatar's actual voice mode will fail to connect. ### MCP tools not working * The endpoint URL must be **publicly reachable** — URLs resolving to private or local addresses (e.g., `localhost`, `192.168.x.x`) are rejected for security. * Your MCP server must respond to the initial connection within a few seconds, or its tools are skipped for that conversation. * See [Adding MCP Tools to Your Avatar](/features/adding-mcp-tools-to-your-avatar) for setup options and design guidance. ### Still stuck? Email **** and include: 1. Your **avatar ID** 2. The **domain** where the avatar is embedded 3. Browser + OS version 4. Any errors from the browser console (screenshots welcome) # Usage Statistics Track how your avatars are being used from the **Usage Statistics** page in the Sentifyd platform. ### What You Can See For each of your avatars, the page shows: * **Number of conversations** — how many conversations users have had with the avatar. * **Total, average, and maximum duration** (in seconds) — how long users engage. * **Used credits** — how much of your plan's conversation allowance the avatar has consumed. * **Rated conversations and average satisfaction score (1–5)** — when users rate a conversation at the end, the ratings are aggregated here so you can monitor quality. ### Filtering * **Search** for a specific avatar by name. * If you belong to an organization, filter between **personal** and **organization** avatars. ### How to Use the Numbers * **Low conversation counts** on a deployed avatar usually point to placement: try the toggler mode on more pages, or promote the shareable link. * **Very short average durations** can mean users aren't finding answers — review the avatar's training, add more knowledge sources, or add conversation examples for the questions users actually ask. * **Low satisfaction scores** are worth investigating: test the avatar yourself with real user questions, tighten the persona description, and make sure escalation (the support request tool) is configured so users are never stuck. * **Used credits** helps you anticipate when you'll need a higher plan tier. # Plans, Credits & Limits ## Plans, Credits & Limits Sentifyd subscriptions work on a simple **credit** system: conversations consume credits by the minute, and your plan gives you a monthly credit allotment. This page explains the mechanics so you can pick the right plan and predict usage. For current prices and included credits, always check the [pricing page](https://sentifyd.io/pricing/). #### How Credits Work * New accounts receive **50 free welcome credits**. No credit card is required. * Conversations consume credits **per minute of conversation time**. * The rate depends on the avatar's voice mode: * **Standard** avatars: 2 credits per minute * **Real-time** avatars: 3 credits per minute #### Plans * Subscription plans (Starter, Growth, Scale, Pro) each include a **monthly credit allotment** that renews every calendar month — on both monthly and annual billing. Annual billing gives a discount on price; the monthly credit allotment is the same. * Unused subscription credits **do not roll over** — the allotment resets each month. * You can also purchase **one-off credit packs**. Subscription credits are consumed first; purchased credits are used after they run out, so packs act as a buffer for busy months. * When you have no credits left, avatars stop accepting new conversations until your allotment renews or you top up — you are never charged surprise overage on the standard tiers. * Enterprise/pay-as-you-go arrangements with metered billing are available — [contact us](mailto:info@sentifyd.io). #### Keeping an Eye on Usage The Usage Statistics page shows conversations, durations, and used credits per avatar, so you can see where your credits go and anticipate when to upgrade. #### Other Limits | Limit | Value | | ----------------------------------------------- | ------------------------------------ | | Documents per training | 5 (16 MB each) | | Conversation examples per training | 25 | | Multilingual locales per avatar (standard mode) | 4 | | Website pages indexed per training URL | ≈150 pages, up to 3 link levels deep | {% hint style="info" %} Need higher limits? Contact **** — several limits can be raised on enterprise arrangements. {% endhint %} # Security, Privacy & AI Compliance Sentifyd is built so that you can deploy an AI avatar on your site responsibly — with transparency toward your users and privacy by default. This page summarizes what Sentifyd handles for you and what you're responsible for as the deployer. {% hint style="info" %} This page is practical guidance, not legal advice. For your specific obligations, consult qualified counsel. {% endhint %} ### AI Transparency (EU AI Act) Under the EU AI Act (Article 50), users must be informed that they are interacting with an AI system. Sentifyd handles this for you by default: * **Built-in AI disclosure and consent.** Before a conversation starts, the widget shows a “Consent for AI conversation” dialog that discloses the AI nature of the avatar and collects the user's consent. * **The avatar never pretends to be human.** If asked, it will confirm it is an AI assistant. * **AI-generated audio/video marking.** The avatar's generated speech and animation are machine-readably marked as AI-generated, as required for synthetic media. **Your responsibility as deployer:** * If you set `terms-accepted="true"` on the embed, the built-in consent dialog is **skipped** — you are attesting that you have already disclosed the AI nature and obtained consent in your own flow (e.g., your app's onboarding or consent manager). Only do this if that is actually true. * Do not use the avatar for **high-risk** purposes under the AI Act (e.g., recruitment decisions, credit scoring, essential-services eligibility, or educational assessment). Sentifyd's terms prohibit such deployments. * If your avatar is modeled on a **real person** (e.g., an Avaturn avatar of your founder), make sure your deployment makes clear that users are interacting with an AI likeness. ### Privacy & Data Handling * **No long-term conversation storage.** Conversation transcripts are kept only briefly (a few hours) to support context and resuming, then discarded. Sentifyd does not train models on your users' conversations. * **User data collection is consent-based.** When the avatar collects personal details (e.g., for a support request), it does so with the user's consent within the conversation. * **Transcript download.** End users can download their own conversation transcript during the conversation. * **Terms and privacy links.** The widget links to Sentifyd's terms and privacy policy by default; replace them with your own using the `terms-href` and `privacy-href` settings so your users see your policies. ### Content Safety All conversations run within AI-guarded environments provided by leading AI platforms. Harmful, unsafe, or non-compliant prompts and responses are detected and blocked automatically, keeping conversations within ethical and legal boundaries. ### Credential Security * The **avatar API key** is safe to expose in your page: it only allows chatting with your avatar, and the **allowed domains** setting prevents it from being used on other websites. Still, treat the shareable link and key with care — conversations consume your credits. You can rotate the key at any time from the avatar page. * For stricter setups, keep the key server-side and use the [Short-lived Avatar Tokens](/manual-web-integration/short-lived-avatar-tokens-advanced) pattern. * Credentials you configure for [MCP tools](/features/adding-mcp-tools-to-your-avatar) are used only server-side and never exposed to end users. ### Quick Deployer Checklist * [ ] Set your own `terms-href` and `privacy-href` links * [ ] Leave the built-in AI consent dialog enabled, **or** provide equivalent disclosure + consent before setting `terms-accepted` * [ ] Configure allowed domains for every site where the avatar is deployed * [ ] Don't deploy for high-risk (AI Act Annex III) purposes * [ ] Rotate the avatar API key if a shareable link or embed leaks