> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmo.humanizing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# User Features

> Interactive features available to visitors using the chat widget including audio responses, language switching, conversation reset, and 3D avatar

## Overview

The chat widget comes with several interactive features designed to create an engaging and accessible experience for your website visitors. These features work together to provide a conversational AI experience that feels natural and intuitive.

<CardGroup cols={2}>
  <Card title="Audio Responses" icon="volume-high">
    Text-to-speech capability with lip-synced avatar animations.
  </Card>

  <Card title="Language Switching" icon="globe">
    Real-time language switching with automatic translation.
  </Card>

  <Card title="Conversation Reset" icon="rotate">
    Start fresh conversations with a single click.
  </Card>

  <Card title="3D Avatar" icon="user-robot">
    Interactive animated character for visual engagement.
  </Card>
</CardGroup>

## Audio Responses (Text-to-Speech)

The chat widget can speak AI responses aloud using text-to-speech technology, creating a more engaging and accessible experience. When enabled, the 3D avatar animates with lip-sync movements that match the spoken audio.

### How Audio Works

When the avatar panel is open and audio is enabled:

1. The AI generates a text response to your visitor's question
2. The response is sent to the TTS (text-to-speech) service
3. Audio is synthesized and played back through the browser
4. The 3D avatar lip-syncs to the audio in real-time

<Note>
  Audio playback only triggers when the avatar panel is visible. If the panel is closed or showing the language selector, responses remain text-only.
</Note>

### Supported TTS Providers

The widget supports two text-to-speech providers:

| Provider            | Description                                                                                                                              |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Microsoft Azure** | High-quality neural voices with extensive language support and viseme data for lip-sync                                                  |
| **ElevenLabs**      | Premium AI voices with natural intonation and expressive speech. Choose from a curated list of named voices — no technical IDs required. |

### Audio Controls

Audio behavior is controlled at the widget level:

* **Avatar Panel Toggle** - When the avatar panel is open, audio plays automatically for new responses
* **Stop Speaking** - Closing the avatar panel or starting a new message stops any ongoing audio
* **Mobile Behavior** - Audio is disabled on mobile devices to optimize the experience

<Tip>
  Configure TTS settings for each supported language in your agent settings. Different languages can use different voices or even different providers for optimal pronunciation.
</Tip>

## Language Switching

The chat widget supports real-time language switching, allowing visitors to interact in their preferred language. This feature provides automatic translation of the interface and AI responses.

### Accessing the Language Selector

**On Desktop:**

1. Click the flag icon in the chat header
2. The language panel opens alongside the chat
3. Select your preferred language from the list
4. The panel automatically closes after selection

**On Mobile:**

1. Tap the flag icon in the chat header
2. The language list displays full-screen
3. Select your preferred language
4. You're returned to the chat view

### What Gets Translated

When a visitor switches languages:

| Element                 | Translation Behavior                                     |
| ----------------------- | -------------------------------------------------------- |
| **Welcome Message**     | Automatically translated to the new language             |
| **Suggested Questions** | Translated to help visitors discover topics              |
| **Interface Text**      | Buttons, placeholders, and labels update instantly       |
| **AI Responses**        | Future responses come in the selected language           |
| **System Messages**     | Language change confirmation appears in the new language |

<Note>
  Previous conversation messages remain in their original language. Only new messages and the welcome message are translated when switching languages.
</Note>

### Language Persistence

The widget remembers your visitor's language preference:

<Steps>
  <Step title="Initial Load">
    Widget detects browser language and uses it if enabled, otherwise uses the default.
  </Step>

  <Step title="Manual Selection">
    When a visitor selects a language, it's saved to browser storage.
  </Step>

  <Step title="Return Visits">
    On subsequent visits, the widget loads with the previously selected language.
  </Step>
</Steps>

### Configuring Available Languages

Control which languages appear in the selector through your agent's [Localization settings](/customization/localization):

* **Enable/Disable Languages** - Choose which languages to offer
* **Set Default Language** - Configure the fallback for unsupported browser languages
* **Exclude Languages** - Remove specific languages from the selector entirely

<Warning>
  If only one language is enabled, the language button is hidden from the widget header to avoid confusion.
</Warning>

## Conversation Reset

The reset feature allows visitors to start a fresh conversation at any time. This clears the current chat history and displays a new welcome message.

### Using the Reset Feature

1. Click the **rotate/refresh icon** in the chat header
2. The conversation is immediately cleared
3. A new welcome message appears
4. The visitor can start asking new questions

### What Reset Does

| Action              | Behavior                                           |
| ------------------- | -------------------------------------------------- |
| **Messages**        | All chat messages are cleared from the widget      |
| **Session ID**      | A new session identifier is generated              |
| **Thread ID**       | The conversation thread is reset for fresh context |
| **Avatar State**    | Any ongoing speech is stopped                      |
| **Input Field**     | Any typed text is cleared                          |
| **Welcome Message** | A fresh welcome message is displayed               |

<Tip>
  The reset feature is useful when visitors want to change topics entirely or if they've encountered an issue and want to start over with a clean slate.
</Tip>

### When to Use Reset

Encourage visitors to use reset when:

* They want to ask about a completely different topic
* The conversation has gone off-track
* They want to see the suggested questions again
* They're testing different queries

## 3D Avatar Panel

The avatar panel provides a visual companion for conversations. A 3D animated character responds to interactions, creating a more personal and engaging experience.

### Avatar Panel Layout

**Desktop View:**

* The avatar panel appears alongside the chat area
* Both panels are visible simultaneously (800px total width)
* The avatar animates while speaking
* Toggle visibility with the bot icon in the header

**Mobile View:**

* The avatar panel is not available on mobile
* Mobile users get the full chat experience without the avatar
* This optimizes performance and screen real estate

### Avatar States

| State        | Description                                       |
| ------------ | ------------------------------------------------- |
| **Idle**     | Avatar displays a neutral, ready state            |
| **Loading**  | Progress indicator shows while avatar assets load |
| **Speaking** | Avatar lip-syncs to audio with natural animations |
| **Error**    | Fallback state if avatar fails to load            |

### Avatar Loading

The 3D avatar requires loading assets (GLB models, animations) when the chat opens:

<Steps>
  <Step title="Chat Opens">
    Widget opens and begins loading avatar assets in the background.
  </Step>

  <Step title="Progress Display">
    A loading indicator shows progress (0-100%).
  </Step>

  <Step title="Ready State">
    Once loaded, the avatar displays in idle state.
  </Step>

  <Step title="Cached">
    Subsequent visits load faster due to browser caching.
  </Step>
</Steps>

<Note>
  Avatar assets are only loaded when the chat widget is opened, not when the page loads. This prevents unnecessary bandwidth usage for visitors who don't use the chat.
</Note>

### Controlling the Avatar Panel

**Show/Hide Toggle:**

* Click the **bot icon** in the header to toggle the avatar panel
* When visible: Bot icon appears with a subtle highlight
* When hidden: BotOff icon indicates the panel is collapsed

**Panel Interactions:**

* Closing the panel stops any ongoing audio
* Switching to language view also stops audio
* The panel state persists during the session

## Feature Comparison by Device

Different features are available depending on the device:

| Feature            | Desktop               | Mobile           |
| ------------------ | --------------------- | ---------------- |
| Chat Interface     | Yes                   | Yes              |
| Avatar Panel       | Yes                   | No               |
| Audio/TTS          | Yes (when panel open) | No               |
| Language Switching | Side panel            | Full-screen view |
| Reset Conversation | Yes                   | Yes              |
| Close Button       | In header             | In header        |

## Message Feedback (Thumbs Up / Thumbs Down)

Visitors can rate individual AI responses directly in the chat widget to indicate whether the answer was helpful.

### How It Works

1. After the agent responds, thumbs up and thumbs down icons appear on the message.
2. The visitor clicks the icon that reflects their experience.
3. Feedback is recorded and aggregated in the **Analytics** dashboard.

### Viewing Feedback Data

Feedback ratings appear as **Thumbs Up** and **Thumbs Down** counts in [Analytics](/agents/analytics). Use these metrics to identify responses that need improvement and track overall satisfaction over time.

<Tip>
  A consistently high thumbs-up ratio indicates your knowledge base and system prompt are well-tuned. Investigate thumbs-down conversations in the [Conversations](/agents/conversations) page to find specific responses to improve.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion icon="volume-high" title="Audio Experience">
    * Configure TTS voices that match your brand personality
    * Set up language-specific voices for natural pronunciation
    * Test audio in all enabled languages before deploying
  </Accordion>

  <Accordion icon="globe" title="Language Support">
    * Only enable languages your knowledge base can support well
    * Test AI responses in each enabled language
    * Consider regional variations (e.g., Brazilian Portuguese vs. European Portuguese)
  </Accordion>

  <Accordion icon="user-robot" title="Avatar Usage">
    * Choose an avatar that represents your brand appropriately
    * Consider the avatar's appearance for your target audience
    * Test avatar loading performance on slower connections
  </Accordion>

  <Accordion icon="mobile-screen" title="Mobile Optimization">
    * Test the chat experience on various mobile devices
    * Verify language switching works smoothly on touchscreens
    * Ensure the close button is easily accessible
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Widget Configuration" icon="sliders" href="/customization/widget">
    Configure welcome messages and suggested questions.
  </Card>

  <Card title="Localization" icon="globe" href="/customization/localization">
    Set up languages and translation settings.
  </Card>

  <Card title="Styling" icon="palette" href="/customization/styling">
    Customize the visual appearance of your widget.
  </Card>

  <Card title="Deployment" icon="code" href="/agents/deployment">
    Get the embed code for your website.
  </Card>
</CardGroup>