# Profile Settings
Source: https://docs.cosmo.humanizing.com/account/profile

Manage your personal account settings, update your profile, change your password, and customize your theme

## Overview

Profile settings allow you to manage your personal account information, change your password, and customize your experience with theme and language preferences. These settings are specific to your user account and apply across all workspaces you belong to.

<Info>
  Profile settings are personal to your account and don't affect other team members in your workspaces.
</Info>

## Accessing Profile Settings

You can access your profile settings in two ways:

<Steps>
  <Step title="From the User Menu">
    Click your **avatar** in the top navigation bar, then select **Account Settings**.
  </Step>

  <Step title="From the Sidebar">
    Click on **Settings** in the left sidebar, then select **Account**.
  </Step>
</Steps>

## Profile Information

The profile section displays your account details and allows you to update your display name.

### Updating Your Name

<Steps>
  <Step title="Navigate to Account Settings">
    Go to **Settings** → **Account** from the sidebar or user menu.
  </Step>

  <Step title="Edit Your Name">
    In the **Profile** card, update the **Full Name** field with your new name.
  </Step>

  <Step title="Save Changes">
    Click **Save** to update your profile.
  </Step>
</Steps>

<Tip>
  Your display name is visible to team members in shared workspaces. Use a name that helps colleagues identify you easily.
</Tip>

### Email Address

Your email address is displayed but cannot be changed from the profile settings. The email is used for:

* Signing in to your account
* Receiving password reset links
* Magic link authentication
* Workspace invitations

| Field              | Description                                |
| ------------------ | ------------------------------------------ |
| **Email**          | Your registered email address (read-only)  |
| **Email Verified** | Shows whether your email has been verified |

<Note>
  If your email shows as "Not Verified", check your inbox for a verification email. A verified email is required for certain features like password reset.
</Note>

## Changing Your Password

Keep your account secure by periodically updating your password.

<Steps>
  <Step title="Navigate to Account Settings">
    Go to **Settings** → **Account**.
  </Step>

  <Step title="Enter Current Password">
    In the **Change Password** card, enter your current password.
  </Step>

  <Step title="Enter New Password">
    Enter your new password (minimum 8 characters).
  </Step>

  <Step title="Confirm New Password">
    Re-enter the new password to confirm it matches.
  </Step>

  <Step title="Update Password">
    Click **Change Password** to save your new password.
  </Step>
</Steps>

### Password Requirements

| Requirement            | Description                                      |
| ---------------------- | ------------------------------------------------ |
| **Minimum Length**     | At least 8 characters                            |
| **Match Confirmation** | New password and confirmation must match exactly |
| **Case Sensitive**     | Passwords are case-sensitive                     |

<Warning>
  After changing your password, you'll remain signed in on your current device. Use your new password for future sign-ins on other devices.
</Warning>

## Theme Settings

Customize the appearance of the Cosmo dashboard with theme options.

### Accessing Theme Settings

<Steps>
  <Step title="Open User Menu">
    Click your **avatar** in the top navigation bar.
  </Step>

  <Step title="Select Theme">
    Hover over **Theme** to see the available options.
  </Step>

  <Step title="Choose Your Theme">
    Select **Light**, **Dark**, or **System** to apply your preference.
  </Step>
</Steps>

### Available Themes

| Theme      | Description                                                      |
| ---------- | ---------------------------------------------------------------- |
| **Light**  | Bright interface with light backgrounds                          |
| **Dark**   | Dark interface that reduces eye strain in low-light environments |
| **System** | Automatically matches your operating system's theme setting      |

<Tip>
  Use the **System** option to automatically switch between light and dark themes based on your device's preferences throughout the day.
</Tip>

## Language Settings

Change the interface language to your preferred language.

### Changing Language

<Steps>
  <Step title="Open User Menu">
    Click your **avatar** in the top navigation bar.
  </Step>

  <Step title="Select Language">
    Hover over **Language** to see available options.
  </Step>

  <Step title="Choose Your Language">
    Select your preferred language. The page will reload to apply the change.
  </Step>
</Steps>

### Supported Languages

| Language    | Code |
| ----------- | ---- |
| **English** | en   |
| **German**  | de   |

<Note>
  Language preferences are stored in a browser cookie and will persist across sessions on the same device.
</Note>

## Account Information

The account information section displays metadata about your account that cannot be edited.

| Field          | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| **User ID**    | Your unique account identifier (used for technical support) |
| **Created At** | The date your account was created                           |

## Signing Out

To sign out of your account:

<Steps>
  <Step title="Open User Menu">
    Click your **avatar** in the top navigation bar.
  </Step>

  <Step title="Sign Out">
    Click **Sign Out** at the bottom of the menu.
  </Step>
</Steps>

You'll be redirected to the home page and will need to sign in again to access your account.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="key" title="Current password is incorrect">
    Make sure you're entering your current password correctly. Passwords are case-sensitive. If you've forgotten your password, sign out and use the **Forgot password?** link on the sign-in page.
  </Accordion>

  <Accordion icon="lock" title="New passwords don't match">
    Ensure both the New Password and Confirm Password fields contain exactly the same value. Check for extra spaces or typos.
  </Accordion>

  <Accordion icon="circle-exclamation" title="Password too short error">
    Your password must be at least 8 characters long. Try a longer password that combines letters, numbers, and symbols for better security.
  </Accordion>

  <Accordion icon="envelope" title="Email not verified">
    Check your email inbox (including spam folder) for a verification email. Click the verification link to confirm your email address.
  </Accordion>

  <Accordion icon="palette" title="Theme not changing">
    If your theme isn't updating, try refreshing the page. Ensure your browser allows cookies, as theme preferences are stored locally.
  </Accordion>

  <Accordion icon="language" title="Language not changing">
    Language changes require a page reload. If the language doesn't change, clear your browser cookies for the site and try again.
  </Accordion>

  <Accordion icon="floppy-disk" title="Profile changes not saving">
    Check your internet connection and try again. If the problem persists, refresh the page and re-enter your changes.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup>
  <Card title="Use Strong Passwords" icon="lock">
    Create passwords with at least 8 characters using a mix of letters, numbers, and symbols.
  </Card>

  <Card title="Change Regularly" icon="arrows-rotate">
    Update your password periodically to maintain account security.
  </Card>

  <Card title="Sign Out on Shared Devices" icon="right-from-bracket">
    Always sign out when using shared or public computers.
  </Card>

  <Card title="Verify Your Email" icon="envelope-circle-check">
    Keep your email verified to ensure you can recover your account if needed.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Workspace Settings" icon="gear" href="/workspace/settings">
    Learn how to manage your workspace configuration.
  </Card>

  <Card title="Manage Team Members" icon="users" href="/workspace/members">
    Invite and manage team members in your workspace.
  </Card>
</CardGroup>


# Analytics
Source: https://docs.cosmo.humanizing.com/agents/analytics

Monitor agent performance with usage metrics, conversation trends, and geographic insights

## Overview

The Analytics dashboard gives you comprehensive insights into how your agent is performing. Track conversation volumes, measure user satisfaction through feedback metrics, and understand where your visitors are coming from geographically.

<Tip>
  Use analytics data to make informed decisions about improving your agent's knowledge base and system prompt.
</Tip>

***

## Accessing Analytics

Navigate to Analytics by selecting your agent from the sidebar and clicking on **Analytics** in the agent menu. You'll see an interactive dashboard with various metrics and visualizations.

***

## Key Metrics

The dashboard displays four primary metrics at the top:

| Metric                  | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| **Total Conversations** | The total number of chat sessions with your agent during the selected period |
| **Total Messages**      | The combined count of all messages exchanged (visitor and agent messages)    |
| **Thumbs Up**           | Number of positive feedback responses from visitors                          |
| **Thumbs Down**         | Number of negative feedback responses from visitors                          |

<Note>
  Feedback metrics (thumbs up/down) help you gauge overall satisfaction. A high ratio of positive to negative feedback indicates your agent is providing helpful responses. Visitors rate responses using thumbs up and thumbs down buttons that appear on each agent message in the chat widget.
</Note>

### Understanding the Metrics

<AccordionGroup>
  <Accordion icon="comments" title="Total Conversations">
    Each conversation represents a unique chat session. A visitor opening the widget and sending messages counts as one conversation, regardless of how many times they return within the session.
  </Accordion>

  <Accordion icon="message" title="Total Messages">
    This counts every message in both directions. It includes visitor questions and agent responses. Higher message counts per conversation may indicate engaged users or complex queries requiring multiple exchanges.
  </Accordion>

  <Accordion icon="thumbs-up" title="Feedback Metrics">
    Visitors can rate agent responses with thumbs up or thumbs down. These ratings help you identify which responses are helpful and which need improvement.
  </Accordion>
</AccordionGroup>

***

## Date Range Selection

Use the date range picker in the top-right corner to analyze specific time periods:

* **Last 7 days** - Default view for recent trends
* **Last 30 days** - Monthly performance overview
* **Custom range** - Select specific start and end dates

<Tip>
  Compare different time periods to identify trends. For example, compare this week to last week to see if your recent knowledge base updates have improved engagement.
</Tip>

***

## Chats Over Time Chart

The interactive line chart shows conversation volume trends over your selected date range:

### What to Look For

| Pattern               | What It Means                                                            |
| --------------------- | ------------------------------------------------------------------------ |
| **Upward trend**      | Growing engagement with your agent                                       |
| **Spikes**            | Increased traffic, possibly from marketing campaigns or product launches |
| **Dips**              | Lower engagement periods (weekends, holidays)                            |
| **Consistent volume** | Stable, predictable usage                                                |

### Using the Chart

* **Hover** over data points to see exact conversation counts for each day
* **Identify patterns** such as weekly cycles or seasonal trends
* **Track growth** over time to measure the impact of improvements

***

## Geographic Distribution

The Chats by Country section shows where your visitors are located:

### World Map View

An interactive map displays chat distribution globally:

* **Hover** over countries to see chat counts
* **Identify** your primary markets
* **Discover** unexpected geographic interest

### Country Data Table

Below the map, a detailed table shows:

| Column      | Description                               |
| ----------- | ----------------------------------------- |
| **Country** | Visitor's geographic location             |
| **Chats**   | Number of conversations from that country |
| **Flag**    | Visual country identifier                 |

<Note>
  Geographic data helps you understand your audience. If you notice significant traffic from non-English speaking countries, consider adding localized content or enabling multiple languages.
</Note>

***

## Channel Distribution

See where conversations originate from:

| Channel              | Description                                             |
| -------------------- | ------------------------------------------------------- |
| **Widget or Iframe** | Visitors using the embedded chat widget on your website |
| **Playground**       | Test conversations from your agent's Playground         |
| **API**              | Conversations initiated through direct API integration  |

### Channel Insights

<AccordionGroup>
  <Accordion icon="desktop" title="Widget/Iframe dominance">
    Most conversations should come from your website widget - this indicates proper deployment and good visibility.
  </Accordion>

  <Accordion icon="flask" title="High Playground usage">
    Significant Playground traffic might indicate team members are actively testing and improving the agent.
  </Accordion>

  <Accordion icon="code" title="API traffic">
    API conversations show programmatic integration, useful for custom applications or third-party integrations.
  </Accordion>
</AccordionGroup>

***

## Top Pages

Track which pages on your website generate the most chat conversations:

| Column              | Description                                       |
| ------------------- | ------------------------------------------------- |
| **Page**            | The URL path where visitors started conversations |
| **Views**           | Total page views                                  |
| **Chats**           | Number of conversations started on that page      |
| **Conversion Rate** | Percentage of page views that resulted in a chat  |

### Using Page Data

* **High conversion pages** - These pages drive engagement; ensure the agent has excellent knowledge about topics on these pages
* **Low conversion pages** - Consider improving widget visibility or page content
* **High-traffic, low-chat pages** - May indicate visitors find the information they need without assistance

<Tip>
  Focus on improving agent knowledge for your highest-converting pages. If visitors frequently chat on your pricing page, make sure pricing information is thoroughly covered in your knowledge base.
</Tip>

***

## Workspace-Level Usage

Beyond individual agent analytics, you can view overall workspace usage:

1. Navigate to **Usage** in the main sidebar
2. View aggregated metrics across all agents in your workspace
3. Compare performance between different agents

<Note>
  Workspace usage analytics show combined activity for all agents. This is useful for tracking overall platform adoption and identifying your most active agents.
</Note>

<Note>
  Credits are only consumed by explicit agent interactions — not by dashboard navigation or background processes. The Usage page shows per-event attribution so you can see exactly what consumed your credits.
</Note>

***

## Analyzing Performance

Use analytics data to continuously improve your agent:

### Weekly Review Process

<Steps>
  <Step title="Check key metrics">
    Review total conversations and feedback ratios. Are conversations increasing? Is feedback mostly positive?
  </Step>

  <Step title="Examine trends">
    Look at the chats over time chart for patterns. Any unexpected spikes or drops?
  </Step>

  <Step title="Review geographic data">
    Check if traffic is coming from expected regions. Consider localization if you see significant international traffic.
  </Step>

  <Step title="Analyze top pages">
    Identify high-converting pages and ensure your agent has strong knowledge coverage for those topics.
  </Step>

  <Step title="Take action">
    Based on your findings, update your knowledge base, refine your system prompt, or adjust widget placement.
  </Step>
</Steps>

### Improvement Strategies

Based on your analytics, consider these actions:

| Finding                       | Suggested Action                                                                                       |
| ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| Low thumbs up ratio           | Review [Conversations](/agents/conversations) to identify problematic responses; update knowledge base |
| High traffic from new country | Add localized content; consider enabling that language                                                 |
| Spike on specific page        | Ensure comprehensive coverage of that page's topic in your sources                                     |
| Declining conversations       | Check widget visibility; review recent changes that may have affected engagement                       |

***

## Best Practices

<AccordionGroup>
  <Accordion icon="calendar" title="Monitor regularly">
    Check analytics weekly to catch issues early and track improvement trends.
  </Accordion>

  <Accordion icon="chart-mixed" title="Compare periods">
    Use date range selection to compare current performance against previous periods.
  </Accordion>

  <Accordion icon="bullseye" title="Set benchmarks">
    Establish baseline metrics for your agent and track progress over time.
  </Accordion>

  <Accordion icon="lightbulb" title="Act on insights">
    Analytics are only valuable if you use them. Make regular improvements based on what you learn.
  </Accordion>

  <Accordion icon="users" title="Share with your team">
    Share analytics insights with stakeholders to demonstrate ROI and gather input on improvements.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="No analytics data showing">
    **Possible causes:**

    * Agent not yet deployed
    * No conversations have occurred yet
    * Date range doesn't include any activity

    **Solutions:**

    * Verify deployment in [Deployment](/agents/deployment) settings
    * Expand the date range to include more history
    * Test the agent through the widget to generate data
  </Accordion>

  <Accordion icon="clock" title="Data seems delayed">
    **Possible causes:**

    * Analytics processing time
    * Browser caching

    **Solutions:**

    * Allow a few minutes for new conversations to appear
    * Refresh the page to see the latest data
  </Accordion>

  <Accordion icon="map" title="Geographic data missing for some countries">
    **Possible causes:**

    * Visitors using VPN
    * Privacy settings blocking location

    **Note:** Some visitors may appear without location data due to privacy settings, which is normal.
  </Accordion>

  <Accordion icon="filter" title="Metrics don't match expectations">
    **Possible causes:**

    * Date range doesn't match expected period
    * Multiple agents in workspace

    **Solutions:**

    * Verify the selected date range
    * Ensure you're viewing the correct agent's analytics
  </Accordion>
</AccordionGroup>

***

## Kiosk Avatar & Voicebot Analytics

Kiosk Avatar and Voicebot channels have dedicated analytics pages with call-specific metrics:

| Metric               | Description                                    |
| -------------------- | ---------------------------------------------- |
| **Total Calls**      | Total number of calls handled by the agent     |
| **Answered**         | Calls that were successfully connected         |
| **Missed**           | Calls where no contact was reached             |
| **Average Duration** | Average call length across the selected period |
| **Answer Rate**      | Percentage of calls that were answered         |

Navigate to your Kiosk Avatar or Voicebot channel and click **Analytics** to access these metrics. Date range filtering is supported.

***

## Next Steps

<CardGroup>
  <Card title="View Conversations" icon="messages" href="/agents/conversations">
    Dive into individual chat sessions for detailed insights.
  </Card>

  <Card title="Improve Knowledge Base" icon="database" href="/sources/overview">
    Add content to address gaps identified in analytics.
  </Card>

  <Card title="Refine System Prompt" icon="flask" href="/agents/playground">
    Adjust your agent's behavior based on performance data.
  </Card>

  <Card title="Check Deployment" icon="rocket" href="/agents/deployment">
    Ensure your agent is properly deployed to maximize engagement.
  </Card>
</CardGroup>


# Viewing Conversations
Source: https://docs.cosmo.humanizing.com/agents/conversations

Monitor and review chat history between your agent and website visitors

## Overview

The Conversations page lets you view and analyze all chat interactions between your agent and website visitors. Monitor what users are asking, how your agent responds, and export conversation data for analysis or compliance purposes.

<Tip>
  Regularly reviewing conversations helps you identify knowledge gaps, common questions, and opportunities to improve your agent's responses.
</Tip>

## Accessing Conversations

Navigate to **Conversations** in your agent's sidebar menu. The page displays a split-view layout:

| Panel           | Purpose                                     |
| --------------- | ------------------------------------------- |
| **Left Panel**  | Scrollable list of all conversation threads |
| **Right Panel** | Detailed view of the selected conversation  |

***

## Conversation List

The left panel shows all conversations (threads) with your agent, sorted by most recent activity.

### Thread Preview

Each thread in the list displays:

* **First message**: The visitor's initial question or message
* **Agent response preview**: Beginning of your agent's first response
* **Message count**: Total messages exchanged in the thread
* **Time since activity**: How long ago the conversation occurred (e.g., "5 minutes ago", "2 hours ago")

### Selecting a Conversation

Click any thread in the list to view its full contents in the right panel. The selected thread is highlighted with a blue background for easy identification.

### Loading More Threads

Conversations are loaded in batches of 50 for performance. When more threads are available:

1. Scroll to the bottom of the thread list
2. Click **Load More** to fetch additional conversations
3. The button shows how many threads are currently loaded out of the total

***

## Viewing Conversation Details

When you select a conversation, the right panel displays the full interaction with two tabs:

### Chat Tab

The **Chat** tab shows the complete message history:

* **User messages**: Displayed in blue bubbles, aligned to the right
* **Agent responses**: Displayed in white/gray bubbles, aligned to the left
* **Timestamps**: Each message shows the date and time it was sent
* **Sources**: If your agent cited knowledge base sources, they appear above the response with a clickable indicator

<Note>
  Timestamps are displayed in your local timezone and follow your browser's locale settings for date/time formatting.
</Note>

### Details Tab

The **Details** tab provides metadata about the conversation:

| Field             | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| **Thread ID**     | Unique identifier for this conversation (useful for support tickets) |
| **Messages**      | Total number of messages exchanged                                   |
| **Created**       | Date and time when the conversation started                          |
| **Last Activity** | When the most recent message was sent                                |
| **First Message** | The visitor's opening question or message                            |

***

## Searching Conversations

Use the search bar at the top of the conversation list to find specific interactions.

### How Search Works

1. Type your query in the search field
2. Wait briefly for results (search is debounced for performance)
3. The thread list updates automatically to show matching conversations
4. Clear the search field to return to the full list

### Search Tips

| Search For        | Example                  |
| ----------------- | ------------------------ |
| Specific topics   | "pricing" or "refund"    |
| Product names     | "premium plan"           |
| Error mentions    | "error" or "not working" |
| Feature questions | "how do I"               |

***

## Filtering by Date

Filter conversations to a specific time range using the date range picker in the conversations toolbar:

<Steps>
  <Step title="Open the Date Picker">
    Click the **date range picker** in the toolbar above the conversation list. It displays the currently selected range (or a placeholder when no filter is active).
  </Step>

  <Step title="Select a Date Range">
    Click a start date on the calendar, then click an end date. The calendar shows two months side-by-side for easy range selection.
  </Step>

  <Step title="Apply Filter">
    The conversation list updates automatically to show only threads within your selected date range.
  </Step>

  <Step title="Clear the Filter">
    Click the **×** on the date range picker, or select the same date twice to reset, to remove the date filter and show all conversations.
  </Step>
</Steps>

<Tip>
  Use date filtering to analyze conversations from specific periods — for example, after launching a new feature or during a promotional campaign.
</Tip>

***

## Exporting Conversations

Export individual conversations for record-keeping, compliance, or analysis. Each conversation can be exported in multiple formats.

### Export Formats

| Format   | Best For                                                                |
| -------- | ----------------------------------------------------------------------- |
| **JSON** | Technical analysis, importing into other tools, programmatic processing |
| **PDF**  | Documentation, sharing with stakeholders, archiving                     |
| **CSV**  | Spreadsheet analysis, bulk data processing, reporting                   |

<Note>
  Export is available across Cosmo channels, including Chatbot and Voicebot conversations.
</Note>

### How to Export

<Steps>
  <Step title="Select a Conversation">
    Click on the thread you want to export from the conversation list.
  </Step>

  <Step title="Open Export Menu">
    Click the **menu button** (three dots ⋯) in the conversation header on the right panel.
  </Step>

  <Step title="Choose Format">
    Select your preferred export format: Export as JSON, Export as PDF, or Export as CSV.
  </Step>

  <Step title="Download">
    The file downloads automatically to your default downloads folder. Filenames include the conversation ID and export date (e.g., `conversation-abc123-2024-01-15.json`).
  </Step>
</Steps>

<Note>
  Exported files contain all messages in the conversation, including timestamps and message roles (user/agent). Source citations are included where applicable.
</Note>

***

## Refreshing Data

Click the **refresh button** (circular arrow icon) to reload the conversation list with the latest data. This is useful when:

* New conversations have occurred since you loaded the page
* You want to see updated message counts
* You're monitoring active conversations throughout the day

***

## Understanding Conversation Patterns

Use the conversation list to identify patterns and improve your agent:

### High Message Counts

Conversations with many messages might indicate:

* Complex questions requiring multiple clarifications
* Engaged users exploring your agent's capabilities
* Potential areas where your knowledge base needs expansion

### Recent Activity

Monitor recent conversations to:

* Catch issues with agent responses quickly
* Understand current user interests and questions
* Identify trending topics or concerns

### Common Questions

When you notice the same questions appearing repeatedly:

1. Copy the visitor's question from the conversation
2. Navigate to **Sources → Q\&A**
3. Create a new Q\&A entry with the question and your ideal answer
4. Your agent will now provide consistent answers to similar questions

<Tip>
  Q\&A sources take priority over other content, making them perfect for ensuring accurate answers to important questions you've identified in conversations.
</Tip>

***

## Best Practices

<AccordionGroup>
  <Accordion icon="calendar" title="Review conversations regularly">
    Set a schedule to review recent conversations - daily or weekly depending on volume. This helps you catch issues early and continuously improve your agent.
  </Accordion>

  <Accordion icon="magnifying-glass" title="Search for problem patterns">
    Periodically search for terms like "error," "don't understand," "wrong," or "help" to find conversations where visitors may have had negative experiences.
  </Accordion>

  <Accordion icon="download" title="Export for compliance">
    If your industry requires conversation records, export conversations regularly in PDF format for archival purposes.
  </Accordion>

  <Accordion icon="lightbulb" title="Use insights to improve">
    When you notice repeated questions or topics, add that content to your knowledge base. If responses are incomplete, update your sources or system prompt.
  </Accordion>

  <Accordion icon="chart-bar" title="Track alongside analytics">
    Combine conversation review with the Analytics page to correlate user questions with traffic patterns and identify your most impactful content.
  </Accordion>

  <Accordion icon="users" title="Share insights with your team">
    Export and share interesting conversations with your team. Customer questions often reveal product or service improvement opportunities beyond just the agent.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion icon="list" title="No conversations showing">
    **Possible causes:**

    * Your agent hasn't had any conversations yet
    * Date filters are excluding all conversations
    * Search query has no matches

    **Solutions:**

    * Deploy your agent and interact with it to create test conversations
    * Clear all filters using the filter dialog
    * Remove or modify your search query
  </Accordion>

  <Accordion icon="clock" title="Old conversations missing">
    **Possible causes:**

    * Date filter is set to recent dates only
    * Conversations may have been deleted
    * Data retention policies may apply

    **Solutions:**

    * Check your date filter settings and clear if necessary
    * Contact support if you believe data should be present
  </Accordion>

  <Accordion icon="file-export" title="Export not downloading">
    **Possible causes:**

    * Browser blocking downloads
    * Pop-up blocker interfering
    * Large conversation causing timeout

    **Solutions:**

    * Check your browser's download permissions and pop-up settings
    * Try a different export format (CSV is typically fastest for large conversations)
    * If the conversation is very long, try again after a moment
  </Accordion>

  <Accordion icon="search" title="Search not finding expected results">
    **Possible causes:**

    * Search looks at message content, not metadata
    * Spelling or phrasing differences

    **Solutions:**

    * Try alternative keywords or partial words
    * Use broader search terms
    * Scroll through conversations manually if searching for a recent interaction
  </Accordion>

  <Accordion icon="arrows-rotate" title="Conversations not updating">
    **Possible causes:**

    * Browser caching old data
    * Page hasn't been refreshed

    **Solutions:**

    * Click the refresh button to reload conversations
    * Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R)
  </Accordion>
</AccordionGroup>

***

## Privacy Considerations

When reviewing conversations, keep these privacy best practices in mind:

* **Handle sensitive data carefully** - If visitors share personal information, handle it according to your privacy policy
* **Team access** - Only workspace members with appropriate permissions can view conversations
* **Data retention** - Consider your data retention policies and export/delete old conversations regularly
* **Compliance** - Ensure your conversation storage practices comply with applicable regulations (GDPR, CCPA, etc.)

***

## Next Steps

<CardGroup>
  <Card title="View Analytics" icon="chart-line" href="/agents/analytics">
    Track usage metrics and identify trends in how visitors interact with your agent.
  </Card>

  <Card title="Add Knowledge Sources" icon="database" href="/sources/overview">
    Expand your agent's knowledge to better answer the questions you see in conversations.
  </Card>

  <Card title="Create Q&A Entries" icon="circle-question" href="/sources/qa-sources">
    Add Q\&A pairs for common questions you've identified in conversations.
  </Card>

  <Card title="Modify System Prompt" icon="flask" href="/agents/playground">
    Adjust your agent's behavior based on conversation insights.
  </Card>
</CardGroup>


# Deployment
Source: https://docs.cosmo.humanizing.com/agents/deployment

Learn how to deploy your Chatbot to your site using the embed script

## Overview

Once you've configured and tested your agent in the Playground, deploying it to your website is straightforward. The platform provides deployment channels that let you add your AI assistant to any website with just a few lines of code.

<Tip>
  Always test your agent thoroughly in the Playground before deploying to production. A well-configured agent makes a great first impression with your visitors.
</Tip>

## Deployment Channels

The Deploy section offers multiple ways to integrate your agent:

<CardGroup>
  <Card title="Chat Widget" icon="message">
    The most common deployment option. Adds a floating chat bubble to your website that visitors can click to interact with your agent.
  </Card>

  <Card title="Help Page" icon="circle-question">
    Host a dedicated help page where users can chat directly with your agent. Ideal for support centers and documentation sites.
  </Card>
</CardGroup>

***

## Chat Widget Deployment

The chat widget is an embeddable component that adds AI-powered chat to any website. It appears as a floating bubble in the corner of your page.

### Getting the Embed Code

Navigate to **Deploy → Chat Widget** in your agent's menu. The embed code section displays two script tags that you'll need to add to your website:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>humanizing.init("YOUR_PUBLIC_KEY");</script>
```

<Note>
  Your agent's unique public key is automatically included in the embed code. This key identifies your specific agent and loads its configuration, styling, and knowledge base.
</Note>

### Copying the Code

1. Locate the **Embed Code** section at the bottom of the Playground page or in the Chat Widget deployment settings
2. Click the **copy button** (clipboard icon) in the top-right corner of the code block
3. The complete embed code is copied to your clipboard

***

## Adding the Script to Your Website

### Basic Installation

Add the embed code to your website's HTML. The scripts should be placed near the closing `</body>` tag for optimal performance:

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <title>Your Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- Cosmo Chatbot Widget -->
  <script src="https://chat.humanizing.com/embed.js"></script>
  <script>humanizing.init("YOUR_PUBLIC_KEY");</script>
</body>
</html>
```

### Placement Options

| Location         | Recommendation  | Use Case                                         |
| ---------------- | --------------- | ------------------------------------------------ |
| Before `</body>` | **Recommended** | Most websites - ensures page content loads first |
| Before `</head>` | Alternative     | Sites needing the widget immediately available   |
| Via tag manager  | Advanced        | Sites using Google Tag Manager or similar tools  |

<Tip>
  Placing scripts at the end of the body allows your page content to load and render before the widget initializes, providing a better user experience.
</Tip>

***

## Platform-Specific Instructions

### WordPress

For WordPress sites, you can add the embed code using one of these methods:

<AccordionGroup>
  <Accordion title="Theme Customizer" icon="brush">
    1. Go to **Appearance → Customize** in your WordPress admin
    2. Find the **Additional CSS/Scripts** section (varies by theme)
    3. Add the embed code to the footer scripts area
    4. Click **Publish** to save changes
  </Accordion>

  <Accordion title="Plugin Method" icon="plug">
    1. Install a header/footer scripts plugin (e.g., "Insert Headers and Footers")
    2. Navigate to the plugin settings
    3. Paste the embed code in the **Footer Scripts** section
    4. Save your changes
  </Accordion>

  <Accordion title="Theme Files" icon="file-code">
    1. Go to **Appearance → Theme File Editor**
    2. Select `footer.php` from the right sidebar
    3. Add the embed code just before the closing `</body>` tag
    4. Click **Update File**

    <Warning>
      Editing theme files directly is not recommended as changes may be lost during theme updates. Use a child theme or plugin method instead.
    </Warning>
  </Accordion>
</AccordionGroup>

### Shopify

Add the chat widget to your Shopify store:

1. Go to **Online Store → Themes** in your Shopify admin
2. Click **Actions → Edit code** on your active theme
3. Open `theme.liquid` from the Layout folder
4. Paste the embed code just before the closing `</body>` tag
5. Click **Save**

### Webflow

For Webflow sites:

1. Open your project in the Webflow Designer
2. Go to **Project Settings → Custom Code**
3. Paste the embed code in the **Footer Code** section
4. Publish your site to apply changes

### React / Next.js

For React-based applications, add the script dynamically:

```jsx theme={null}
import { useEffect } from 'react';

function ChatWidget() {
  useEffect(() => {
    // Load the embed script
    const script = document.createElement('script');
    script.src = 'https://chat.humanizing.com/embed.js';
    script.async = true;
    document.body.appendChild(script);

    // Initialize after script loads
    script.onload = () => {
      window.humanizing.init('YOUR_PUBLIC_KEY');
    };

    return () => {
      document.body.removeChild(script);
    };
  }, []);

  return null;
}

export default ChatWidget;
```

Then include the component in your app layout or specific pages where you want the widget.

### Vue.js

For Vue applications:

```vue theme={null}
<script setup>
import { onMounted, onUnmounted } from 'vue';

let script = null;

onMounted(() => {
  script = document.createElement('script');
  script.src = 'https://chat.humanizing.com/embed.js';
  script.async = true;
  script.onload = () => {
    window.humanizing.init('YOUR_PUBLIC_KEY');
  };
  document.body.appendChild(script);
});

onUnmounted(() => {
  if (script) {
    document.body.removeChild(script);
  }
});
</script>

<template>
  <!-- Your component content -->
</template>
```

### Google Tag Manager

To deploy via Google Tag Manager:

1. Create a new **Custom HTML** tag in GTM
2. Paste the embed code in the HTML field
3. Set the trigger to **All Pages** (or specific pages)
4. Test in Preview mode
5. Publish your container

***

## Widget Customization

Before deploying, customize your widget appearance in the **Deploy → Chat Widget** settings:

### Styling Options

| Setting             | Description                                     |
| ------------------- | ----------------------------------------------- |
| **Avatar**          | Choose the 3D avatar that represents your agent |
| **Appearance**      | Light or dark theme for the chat interface      |
| **Brand Color**     | Your primary accent color                       |
| **Bubble Position** | Left or right corner of the screen              |
| **Bubble Icon**     | Custom icon for the chat bubble                 |

### Content Settings

| Setting                 | Description                                 |
| ----------------------- | ------------------------------------------- |
| **Welcome Message**     | Initial greeting when chat opens            |
| **Header Title**        | Custom title in the widget header           |
| **Suggested Questions** | Pre-populated questions to help users start |
| **Languages**           | Available language options for visitors     |

<Note>
  All customization changes require clicking **Save** before they take effect. The live preview in the settings page shows how changes will look.
</Note>

***

## Privacy notice template

The privacy and data-processing guidance now has a dedicated section. Use the expanded template for Voicebot, Chatbot, and Kiosk Avatar deployments.

<Card title="Open the Privacy Notice Template" icon="file-lines" href="/data-protection/privacy-notice-template">
  Adapt the template to your enabled channels and link it to your full privacy notice.
</Card>

***

## Verifying Your Deployment

After adding the embed code to your website:

<Steps>
  <Step title="Clear cache">
    Clear your browser cache and any CDN/server caches to ensure the latest version loads.
  </Step>

  <Step title="Visit your site">
    Navigate to your website and look for the chat bubble in the corner you specified.
  </Step>

  <Step title="Test the widget">
    Click the bubble and ask a test question to verify the agent responds correctly.
  </Step>

  <Step title="Check mobile">
    Test on mobile devices to ensure the widget is accessible and functional.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Widget not appearing" icon="eye-slash">
    **Possible causes:**

    * Script not loading due to Content Security Policy (CSP)
    * JavaScript error on the page blocking execution
    * Ad blocker interfering with the widget

    **Solutions:**

    * Check browser console for errors (F12 → Console)
    * Add the widget domain to your CSP allowlist
    * Disable ad blockers temporarily to test
    * Verify the embed code is correctly placed in your HTML
  </Accordion>

  <Accordion title="Widget loads but doesn't respond" icon="comment-slash">
    **Possible causes:**

    * Invalid or expired public key
    * Network connectivity issues
    * Agent not properly configured

    **Solutions:**

    * Verify the public key matches your agent
    * Check your agent is active in the dashboard
    * Test in the Playground to ensure the agent works
  </Accordion>

  <Accordion title="Styling looks incorrect" icon="palette">
    **Possible causes:**

    * CSS conflicts with your website styles
    * Unsaved changes in widget settings
    * Browser caching old styles

    **Solutions:**

    * The widget uses shadow DOM to isolate styles, but global resets may affect it
    * Save changes in the Chat Widget settings page
    * Hard refresh your page (Ctrl+Shift+R / Cmd+Shift+R)
  </Accordion>

  <Accordion title="Widget appears on wrong pages" icon="map-pin">
    **Possible causes:**

    * Embed code added to global template

    **Solutions:**

    * Use conditional logic in your CMS to show the widget only on specific pages
    * Use Google Tag Manager with page-specific triggers
    * For developers: conditionally render the script based on route
  </Accordion>
</AccordionGroup>

***

## Security Considerations

<Warning>
  Never expose your agent's admin credentials or API keys in client-side code. The public key in the embed code is designed to be public and is the only credential needed for the widget.
</Warning>

### Best Practices

* **Use HTTPS**: Always serve your website over HTTPS to ensure secure communication with the widget
* **Review content**: The agent only responds based on its knowledge base - ensure no sensitive information is included in sources
* **Monitor conversations**: Regularly review conversation logs for any issues or abuse

***

## Help Page Deployment

For a standalone help page experience:

1. Navigate to **Deploy → Help Page** in your agent's menu
2. Click **Setup** to configure your help page
3. Customize the page appearance and branding
4. Share the provided URL or embed it in your site

The help page provides a full-screen chat experience, ideal for:

* Dedicated support portals
* Documentation search
* Customer self-service centers

***

## Next Steps

<CardGroup>
  <Card title="Monitor Conversations" icon="messages" href="/agents/conversations">
    Review chat history and see what visitors are asking.
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/agents/analytics">
    Track usage metrics and identify trends in user behavior.
  </Card>

  <Card title="Add More Sources" icon="database" href="/sources/overview">
    Expand your agent's knowledge with additional content.
  </Card>

  <Card title="Customize Styling" icon="palette" href="/customization/styling">
    Fine-tune colors, appearance, and widget behavior.
  </Card>
</CardGroup>


# Onboarding
Source: https://docs.cosmo.humanizing.com/agents/onboarding

Step-by-step guide to creating your first Chatbot through the onboarding wizard

## Overview

The onboarding wizard guides you through creating a fully configured AI agent in just a few minutes. The process automatically discovers your website content, extracts your brand colors, and trains your agent on your knowledge base.

<Tip>
  The onboarding wizard is designed to get you up and running quickly. You can always customize and add more content to your agent after the initial setup.
</Tip>

## The 4-Step Process

<Steps>
  <Step title="Enter Your Domain">
    Provide your website URL to begin content discovery
  </Step>

  <Step title="Fetch & Select URLs">
    Review discovered pages and choose which content to import
  </Step>

  <Step title="Configure Branding">
    Customize your agent's appearance with avatar, theme, and colors
  </Step>

  <Step title="Content Ingestion">
    Watch as your agent is created and trained on your content
  </Step>
</Steps>

***

## Step 1: Enter Your Domain

The first step begins with identifying your website and naming your agent.

### Agent Name

Give your agent a descriptive name that reflects its purpose. This name appears in the dashboard and helps you identify the agent among multiple agents in your workspace.

<Note>
  Choose a name that's meaningful to your team. For example: "Sales Support Agent", "Product Help Bot", or "Customer FAQ Assistant".
</Note>

### Default Language

Select the default language your agent will use to greet visitors and respond to conversations. This sets the agent's conversation language independently from the app UI language.

<Tip>
  For German-market deployments, select **German** here to ensure your agent greets visitors in German by default. You can change this anytime from the agent's localization settings.
</Tip>

### Website Domain

Enter your main website URL (e.g., `https://yourdomain.com`). The platform uses this to:

* **Discover pages**: Automatically find all crawlable pages on your domain
* **Extract branding**: Detect your brand colors for widget customization
* **Set context**: Help your agent understand where it will be deployed

| Input Format   | Example               | Result                        |
| -------------- | --------------------- | ----------------------------- |
| Full URL       | `https://example.com` | Uses as-is                    |
| Domain only    | `example.com`         | Adds `https://` automatically |
| With subdomain | `docs.example.com`    | Respects subdomain            |

***

## Step 2: Fetch & Select URLs

After entering your domain, the platform automatically discovers all available pages using intelligent web crawling.

### URL Discovery

The crawler finds all public pages on your domain and displays them in a list. You'll see:

* **Total pages found**: The number of pages discovered
* **Page URLs**: Full URLs of each discovered page
* **Selection controls**: Options to select, deselect, or filter pages

<Tip>
  The URL discovery typically finds up to 100 pages during onboarding. You can add more sources later from the Sources section.
</Tip>

### Filtering Options

Use the built-in filters to refine your selection:

| Filter      | Purpose                               | Example                                    |
| ----------- | ------------------------------------- | ------------------------------------------ |
| **Search**  | Find specific URLs by keyword         | Search for "product" to find product pages |
| **Exclude** | Remove URLs containing specific terms | Exclude "blog" to skip blog posts          |

### Selecting Content

Choose pages that contain information your agent should know:

<AccordionGroup>
  <Accordion title="What to include" icon="check">
    * Product or service pages
    * FAQ and help documentation
    * About and contact pages
    * Pricing information
    * Feature descriptions
    * Terms of service and policies
  </Accordion>

  <Accordion title="What to consider excluding" icon="xmark">
    * Blog posts (unless relevant to support)
    * News articles or press releases
    * Login or account pages
    * Empty or placeholder pages
    * Duplicate content pages
  </Accordion>
</AccordionGroup>

<Warning>
  Non-scrapable file types (images, PDFs, videos, etc.) are automatically filtered out. Only web pages with text content are included.
</Warning>

### Managing Your Selection

* **Individual selection**: Click checkboxes to select or deselect specific URLs
* **Bulk selection**: Use shift+click to select a range of URLs
* **Remove URLs**: Click the trash icon to remove unwanted URLs from the list
* **Clear all**: Reset your selection and start fresh

***

## Step 3: Configure Branding

This step customizes your agent's visual appearance to match your brand identity.

### Avatar Selection

Choose a 3D avatar that will represent your agent. The avatar:

* Appears in the chat widget
* Animates and speaks responses using text-to-speech
* Creates a more engaging, human-like experience

<CardGroup>
  <Card title="Browse Gallery" icon="images">
    Select from our collection of pre-made avatars with different personalities and styles.
  </Card>

  <Card title="Change Anytime" icon="arrows-rotate">
    You can always change your avatar later from the agent settings.
  </Card>
</CardGroup>

### Appearance Theme

Select between light and dark mode for your chat widget:

| Theme     | Best For                                                             |
| --------- | -------------------------------------------------------------------- |
| **Light** | Websites with light backgrounds, professional/corporate sites        |
| **Dark**  | Websites with dark backgrounds, tech/gaming sites, modern aesthetics |

### Brand Colors

The platform automatically extracts colors from your website:

* **Accent color**: Your primary brand color
* **Dark color**: A darker shade from your site
* **Light color**: A lighter shade from your site

<Tip>
  If automatic extraction doesn't find your exact brand colors, you can manually enter a hex code or use the color picker.
</Tip>

You can customize your primary color by:

1. **Clicking extracted colors**: Select from automatically detected brand colors
2. **Using the color picker**: Choose any color visually
3. **Entering a hex code**: Type an exact color value (e.g., `#3B82F6`)

***

## Step 4: Content Ingestion

Once you click "Create Agent", the platform begins building your AI assistant. This process runs automatically and shows real-time progress.

### Progress Stages

The creation process includes several stages:

<Steps>
  <Step title="Creating Agent">
    Setting up your agent's configuration and system prompt in the database.
  </Step>

  <Step title="Creating Widget">
    Generating the embeddable chat widget with your branding settings.
  </Step>

  <Step title="Preparing Sources">
    Initializing the knowledge base and preparing your selected URLs for processing.
  </Step>

  <Step title="Processing Pages">
    Crawling each selected URL, extracting text content, and creating embeddings for semantic search.
  </Step>

  <Step title="Building Knowledge">
    Indexing all processed content into the vector database for fast, accurate retrieval.
  </Step>
</Steps>

### Progress Tracking

During ingestion, you'll see:

| Metric               | Description                               |
| -------------------- | ----------------------------------------- |
| **Overall progress** | Percentage of total completion            |
| **Completed**        | Number of pages successfully processed    |
| **In Progress**      | Pages currently being processed           |
| **Failed**           | Pages that couldn't be processed (if any) |
| **Total**            | Total pages being trained                 |

<Note>
  Processing time depends on the number of pages selected. Most agents complete in 1-3 minutes for 50-100 pages.
</Note>

### Handling Failures

If some pages fail to process:

* The agent will still be created with successfully processed pages
* You'll see a summary of failed pages
* You can retry failed sources later from the Sources section
* Common failure reasons: pages blocked by robots.txt, authentication required, or temporary network issues

### Completion

When processing finishes successfully:

1. A success notification appears
2. You're automatically redirected to the **Playground**
3. You can immediately start testing your agent with real questions

***

## After Onboarding

Once your agent is created, you can continue customizing and improving it:

<CardGroup>
  <Card title="Test in Playground" icon="flask" href="/agents/playground">
    Ask questions and see how your agent responds. Fine-tune the system prompt for better answers.
  </Card>

  <Card title="Add More Sources" icon="database" href="/sources/overview">
    Import additional web pages, add custom text, or create Q\&A pairs to expand knowledge.
  </Card>

  <Card title="Customize Widget" icon="palette" href="/customization/styling">
    Adjust colors, backgrounds, position, and other visual settings for your chat widget.
  </Card>

  <Card title="Deploy to Website" icon="code" href="/agents/deployment">
    Get the embed script and add your agent to your live website.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="No pages found during URL discovery" icon="circle-exclamation">
    **Possible causes:**

    * The domain might be blocking crawlers via `robots.txt`
    * The website might require authentication
    * There could be a typo in the domain URL

    **Solutions:**

    * Double-check the URL is correct
    * Try with or without `www.`
    * Contact your webmaster about crawler access
    * Manually add URLs after agent creation
  </Accordion>

  <Accordion title="Brand colors not detected" icon="palette">
    **Possible causes:**

    * The website doesn't have clear brand colors in its CSS
    * Colors are defined in images rather than code
    * The website is blocking external access

    **Solutions:**

    * Use the manual color picker or enter your hex code directly
    * Check your brand guidelines for exact color values
  </Accordion>

  <Accordion title="Pages failing during ingestion" icon="triangle-exclamation">
    **Possible causes:**

    * Individual pages may be blocking access
    * Content might be dynamically loaded (JavaScript-heavy)
    * Pages may have timed out during processing

    **Solutions:**

    * The agent will work with successfully processed pages
    * Retry failed sources from the Sources section later
    * Consider using Q\&A sources for critical content that won't scrape
  </Accordion>

  <Accordion title="Ingestion taking too long" icon="clock">
    **Possible causes:**

    * Large number of pages selected
    * Pages with lots of content
    * Heavy traffic on the processing system

    **Solutions:**

    * Be patient - large knowledge bases take longer to build
    * Consider starting with fewer pages and adding more later
    * The progress bar shows real-time status
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Start focused, expand later">
    Begin with 20-50 high-quality pages rather than importing everything. It's easier to expand a working agent than to fix one with too much irrelevant content.
  </Accordion>

  <Accordion icon="magnifying-glass" title="Review discovered URLs carefully">
    Take time to exclude pages that aren't relevant to customer questions. Quality of sources matters more than quantity.
  </Accordion>

  <Accordion icon="robot" title="Test immediately after creation">
    Use the Playground to ask real questions right away. This helps you identify gaps in your knowledge base early.
  </Accordion>

  <Accordion icon="arrows-rotate" title="Iterate on your system prompt">
    The default system prompt works well, but customizing it based on test results will improve your agent's responses significantly.
  </Accordion>
</AccordionGroup>


# Chatbot Overview
Source: https://docs.cosmo.humanizing.com/agents/overview

Learn how Cosmo's Chatbot channel answers visitors on your website

## What is the Chatbot?

The Chatbot is Cosmo's website channel. It adds an AI-powered chat widget to your site so visitors can ask questions, get support, and interact with your brand without waiting for a human reply.

<Tip>
  Cosmo uses one AI agent across the Chatbot, Voicebot, and Kiosk Avatar. The Chatbot is the channel most teams deploy first.
</Tip>

## Channels

Cosmo by Humanizing supports three channels:

| Channel          | Description                                                                                                                                         | Deployment                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| **Chatbot**      | A chat widget embedded on your website. Visitors click the chat bubble to ask questions, get support, and interact with your brand.                 | Embed script on any website                        |
| **Voicebot**     | A phone channel that answers calls, speaks naturally, uses your knowledge base, and can route or hand off conversations.                            | Assigned phone number or forwarded business number |
| **Kiosk Avatar** | A kiosk-based front desk experience for offices, hotels, and lobbies. Greets visitors, searches contacts, and manages check-ins with a guided flow. | Public URL on a tablet or touchscreen              |

<Note>
  You manage the same AI agent across these channels. Each channel has its own setup, styling, and deployment options.
</Note>

### Chatbot

The Chatbot powers an embeddable chat widget with:

* RAG-powered responses from your knowledge base (web pages, text, Q\&A pairs)
* 3D avatar with text-to-speech
* Customizable themes, colors, and widget positioning
* Deploy with one line of embed code

See the [Chatbot Onboarding](/agents/onboarding) guide for setup instructions.

### Kiosk Avatar

The Kiosk Avatar is designed for physical locations. It provides:

* Multi-screen kiosk flow (language selection, visit type, contact search, calling, confirmation)
* Employee contact directory with CSV import
* Multilingual visitor welcome in 45+ languages
* Portrait and landscape kiosk orientations
* Deploy via a simple public URL (`/a/[publicKey]`) on any touchscreen

See the [Kiosk Avatar Overview](/receptionist/overview) for full documentation.

## Core Concepts

### Knowledge Base

Cosmo has a **knowledge base** - a collection of information sources that the AI agent uses to answer questions. Your knowledge base can include:

| Source Type      | Description                                         | Best For                                 |
| ---------------- | --------------------------------------------------- | ---------------------------------------- |
| **Web Sources**  | Pages from your website imported via URL or sitemap | Product pages, documentation, blog posts |
| **Text Sources** | Custom written content you provide                  | Company policies, internal knowledge     |
| **Q\&A Sources** | Specific question-answer pairs                      | FAQs, common support queries             |

The more relevant content you add to your knowledge base, the more helpful Cosmo becomes across every channel.

### Avatar

Cosmo can use a **3D avatar** in visual channels such as the Chatbot and Kiosk Avatar. Avatars:

* Animate and speak responses using text-to-speech
* Create a more engaging, human-like experience
* Can be customized to match your brand personality

### System Prompt

The **system prompt** defines Cosmo's personality, behavior, and response style. You can customize:

* The AI agent's name and role
* How it greets users
* Its communication style (formal, friendly, technical)
* Specific instructions for handling certain topics

### Widget

The **widget** is the chat interface that appears on your website. It's how visitors interact with your agent. The widget includes:

* A chat bubble that opens the conversation
* A message input area
* The avatar display
* Language and voice options for visitors

## Chatbot Lifecycle

<Steps>
  <Step title="Create">
    Create your AI agent through the onboarding wizard by entering your website domain. Cosmo will automatically discover and suggest content to import.
  </Step>

  <Step title="Train">
    Add knowledge sources to teach Cosmo about your business. Import web pages, add custom text, and create Q\&A pairs for common questions.
  </Step>

  <Step title="Customize">
    Configure Cosmo's appearance, behavior, and widget styling. Choose an avatar, set colors, and write the perfect system prompt.
  </Step>

  <Step title="Deploy">
    Generate an embed script and add it to your website. Your Chatbot is now live and ready to help visitors.
  </Step>

  <Step title="Monitor">
    Track conversations, view analytics, and continuously improve Cosmo based on visitor interactions.
  </Step>
</Steps>

## Key Features

<CardGroup>
  <Card title="RAG-Powered Responses" icon="magnifying-glass">
    Cosmo uses Retrieval-Augmented Generation (RAG) to find relevant content from your knowledge base and generate accurate, contextual responses.
  </Card>

  <Card title="Multi-Language Support" icon="globe">
    Serve visitors in their preferred language with built-in localization support for the widget interface.
  </Card>

  <Card title="Conversation History" icon="clock-rotate-left">
    Review past conversations to understand what visitors are asking and how your agent is responding.
  </Card>

  <Card title="Analytics Dashboard" icon="chart-line">
    Track usage metrics, conversation volumes, and identify popular topics to optimize your agent.
  </Card>
</CardGroup>

## Agent vs Workspace

Understanding the relationship between agents and workspaces:

| Concept       | Description                                                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Workspace** | A container for organizing AI agents and managing team access. Each workspace can have multiple agents and members.                                      |
| **AI agent**  | The shared assistant that powers Cosmo's Chatbot, Voicebot, and Kiosk Avatar channels. Each agent has its own knowledge base, settings, and deployments. |

<Note>
  You can create multiple AI agents within a single workspace - for example, one for sales inquiries and another for technical support, each trained on different content.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion icon="book" title="Start with quality content">
    Focus on adding accurate, helpful content to your knowledge base. Well-written source material leads to better responses.
  </Accordion>

  <Accordion icon="flask" title="Test before deploying">
    Use the Playground to test Cosmo with real questions before deploying to your website. Refine your system prompt based on responses.
  </Accordion>

  <Accordion icon="arrows-rotate" title="Iterate and improve">
    Review conversations regularly to identify gaps in your knowledge base. Add new content to address common questions Cosmo couldn't answer.
  </Accordion>

  <Accordion icon="bullseye" title="Keep prompts focused">
    Write clear, specific system prompts that define exactly how your agent should behave. Avoid overly broad instructions.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Create a Chatbot" icon="sparkles" href="/agents/onboarding">
    Follow our step-by-step guide to create and configure a website chatbot.
  </Card>

  <Card title="Create a Kiosk Avatar" icon="building" href="/receptionist/overview">
    Set up an AI-powered front desk experience for visitor management.
  </Card>

  <Card title="Add Knowledge Sources" icon="database" href="/sources/overview">
    Learn how to train Cosmo with web pages, text, and Q\&A content.
  </Card>

  <Card title="Deploy to Your Website" icon="code" href="/agents/deployment">
    Get the embed code and go live with your Chatbot.
  </Card>
</CardGroup>


# Playground
Source: https://docs.cosmo.humanizing.com/agents/playground

Test your Chatbot, modify prompts, use templates, and preview the chat widget in real-time

## Overview

The Playground is your testing environment for fine-tuning your agent's behavior before deploying it to your website. Here you can modify the system prompt, select from pre-built templates, and see how your agent responds to questions in real-time.

<Tip>
  Always test your agent in the Playground before deploying. It's the fastest way to ensure your agent behaves as expected and provides accurate responses.
</Tip>

## Accessing the Playground

Navigate to the Playground by selecting your agent from the sidebar and clicking on **Playground** in the agent menu. The Playground opens with a split-view layout:

| Panel           | Purpose                                                  |
| --------------- | -------------------------------------------------------- |
| **Left Panel**  | Configuration controls for prompt editing and embed code |
| **Right Panel** | Live chat widget preview for testing                     |

***

## System Prompt (Instructions)

The system prompt, also called "Instructions," defines how your agent behaves, responds, and interacts with users. It's the core configuration that shapes your agent's personality and capabilities.

### What the System Prompt Controls

Your system prompt influences:

* **Personality**: Friendly, professional, technical, casual
* **Knowledge boundaries**: What topics the agent should or shouldn't discuss
* **Response format**: Length, structure, use of bullet points or paragraphs
* **Greeting behavior**: How the agent welcomes users
* **Escalation rules**: When to suggest contacting human support
* **Language and tone**: Formal vs informal communication style

### Editing the Prompt

The Playground provides a text editor for modifying your agent's system prompt:

1. Locate the **Instructions (System prompt)** section in the left panel
2. Edit the text directly in the textarea
3. Click **Save** to apply your changes

<Note>
  Changes are not saved automatically. You'll see the Save button enabled when you have unsaved modifications. A confirmation dialog will appear if you try to navigate away with unsaved changes.
</Note>

### Fullscreen Editor

For longer prompts or more comfortable editing, use the fullscreen editor:

1. Click the **Open in Editor** button below the textarea
2. Edit your prompt in the expanded modal view
3. Click **Apply Changes** to return to the main view
4. Click **Save** to persist your changes

The fullscreen editor provides more space and is particularly useful for complex system prompts with multiple sections.

### Widget Context Placeholders

When your agent is embedded as a chat widget, you can reference page and custom context directly in the system prompt. Add placeholders with double curly braces, such as `{{ page_path }}` or `{{ location }}`.

Built-in page placeholders are available automatically:

| Placeholder         | Description                                   |
| ------------------- | --------------------------------------------- |
| `{{ page_url }}`    | Current page URL without query string or hash |
| `{{ page_origin }}` | Current site origin                           |
| `{{ page_path }}`   | Current path on the site                      |

For example, on `https://example.com/products/widget?utm_source=newsletter#details`, `{{ page_url }}` resolves to `https://example.com/products/widget`, `{{ page_origin }}` resolves to `https://example.com`, and `{{ page_path }}` resolves to `/products/widget`.

For custom values, ask your website developer to pass a `context` object in the widget embed code:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch"
    }
  });
</script>
```

Then use the matching placeholder in your instructions:

```text theme={null}
You are answering for the {{ location }} location.
The visitor is currently on {{ page_path }}.
```

<Note>
  Context values are inserted only where your prompt contains matching placeholders. If a key is missing, the placeholder remains visible so you can spot the mismatch during testing.
</Note>

For the full setup, see [Widget Context](/chat-widget/context).

***

## Prompt Templates

Templates provide pre-configured system prompts optimized for common use cases. They're a great starting point that you can use as-is or customize further.

### Template Categories

The template selector organizes prompts into three groups:

| Category              | Description                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| **Base Instructions** | The default system prompt recommended for most use cases. Provides balanced, helpful responses.    |
| **Templates**         | Pre-built prompts optimized for specific scenarios (customer support, sales, technical help, etc.) |
| **Custom prompt**     | Your own custom instructions, either written from scratch or modified from a template              |

### Using Templates

<Steps>
  <Step title="Open Template Selector">
    Click the dropdown menu in the Instructions section to view available templates.
  </Step>

  <Step title="Select a Template">
    Choose a template from the list. The prompt textarea will immediately update with the selected template's content.
  </Step>

  <Step title="Customize (Optional)">
    Modify the template text to fit your specific needs. The selector will automatically switch to "Custom prompt" once you make changes.
  </Step>

  <Step title="Save Changes">
    Click Save to apply the new instructions to your agent.
  </Step>
</Steps>

### Reset to Default

If you've made changes and want to start fresh, click the **reset button** (circular arrow icon) next to the template selector. This restores the Base Instructions template.

<Warning>
  Resetting to default will replace your current instructions. Make sure to copy any custom text you want to preserve before resetting.
</Warning>

### Template Auto-Detection

The Playground intelligently detects when your instructions match a known template:

* If your text exactly matches a template, that template is shown as selected
* If you modify any character, the selector switches to "Custom prompt"
* Selecting "Custom prompt" restores your previously saved instructions

***

## Live Widget Preview

The right panel displays a fully functional preview of your chat widget. This is the same widget your website visitors will see.

### Testing Your Agent

Use the preview to test your agent's responses:

1. Type a question in the chat input
2. Send the message to see how your agent responds
3. Evaluate the response quality and accuracy
4. Adjust the system prompt if needed
5. Repeat until satisfied with the results

<Tip>
  Test with a variety of questions that your actual users might ask. Include edge cases and questions that might be outside your agent's intended scope to see how it handles them.
</Tip>

### What to Test

| Test Category            | Example Questions                                               |
| ------------------------ | --------------------------------------------------------------- |
| **Core knowledge**       | Questions your agent should definitely answer from your sources |
| **Edge cases**           | Ambiguous or unusual questions                                  |
| **Out of scope**         | Topics your agent shouldn't discuss                             |
| **Conversation flow**    | Multi-turn conversations with follow-up questions               |
| **Tone and personality** | Check that responses match your desired communication style     |

***

## Embed Code

The Playground provides the embed code snippet you'll use to add the chat widget to your website.

### Getting the Embed Code

The embed code section displays two script tags:

```html theme={null}
<script src="https://your-widget-url/embed.js"></script>
<script>humanizing.init("YOUR_PUBLIC_KEY");</script>
```

### Copying to Clipboard

1. Locate the **Embed Code** section at the bottom of the left panel
2. Click the **copy button** (clipboard icon) in the top-right corner of the code block
3. The code is copied to your clipboard, ready to paste into your website

<Note>
  The embed code includes your agent's unique public key. This key identifies your specific agent and loads its configuration.
</Note>

### Where to Add the Code

Add the embed code to your website's HTML, typically in one of these locations:

| Location            | Best For                                     |
| ------------------- | -------------------------------------------- |
| Before `</body>`    | Most websites - ensures page loads first     |
| Before `</head>`    | Sites that need widget available immediately |
| Through tag manager | Sites using Google Tag Manager or similar    |

For detailed deployment instructions, see the [Deployment guide](/agents/deployment).

***

## Saving Changes

The Playground tracks all modifications to your agent's configuration.

### Save Button States

| State        | Appearance       | Meaning                    |
| ------------ | ---------------- | -------------------------- |
| **Disabled** | Grayed out       | No changes to save         |
| **Enabled**  | Active           | Unsaved changes exist      |
| **Saving**   | "Saving..." text | Save in progress           |
| **Saved**    | "Saved" text     | Changes successfully saved |

### Unsaved Changes Warning

If you try to navigate away with unsaved changes:

1. A confirmation dialog appears
2. Choose **Leave without saving** to discard changes
3. Choose **Save and leave** to save first, then navigate
4. Choose **Cancel** to stay on the page

<Tip>
  Get into the habit of saving after each meaningful change. This way you can test incrementally and know exactly which change affected the agent's behavior.
</Tip>

***

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Start with a template">
    Begin with the Base Instructions or a relevant template. They're already optimized for common use cases and provide a solid foundation.
  </Accordion>

  <Accordion icon="flask" title="Test incrementally">
    Make one change at a time and test before making additional modifications. This helps you understand exactly what effect each change has.
  </Accordion>

  <Accordion icon="clipboard-list" title="Keep a testing checklist">
    Maintain a list of questions to test after each change. Include your most common customer questions and known edge cases.
  </Accordion>

  <Accordion icon="pen" title="Be specific in prompts">
    Vague instructions lead to inconsistent responses. Instead of "be helpful," specify "provide step-by-step instructions when explaining how to do something."
  </Accordion>

  <Accordion icon="shield" title="Set boundaries">
    Explicitly tell your agent what topics to avoid and when to suggest contacting human support. This prevents inappropriate responses.
  </Accordion>

  <Accordion icon="book" title="Reference your knowledge base">
    Remind your agent in the system prompt that it should answer from the provided knowledge base. This improves accuracy and reduces hallucination.
  </Accordion>
</AccordionGroup>

***

## Example System Prompts

### Customer Support Agent

```text theme={null}
You are a friendly customer support assistant for [Company Name].

Your role:
- Answer questions about our products and services
- Help customers troubleshoot common issues
- Guide users to relevant documentation

Guidelines:
- Always be polite and patient
- If you don't know the answer, say so and suggest contacting support@company.com
- Keep responses concise but thorough
- Use bullet points for step-by-step instructions

Never:
- Make promises about refunds or compensation
- Share internal company information
- Discuss competitors
```

### Technical Documentation Assistant

```text theme={null}
You are a technical documentation assistant for [Product Name].

Your expertise:
- API documentation and usage examples
- Configuration and setup guides
- Troubleshooting common errors

Communication style:
- Use technical terminology appropriate for developers
- Provide code examples when relevant
- Be precise and accurate

When users ask about features not in the documentation:
- Clearly state that the feature isn't documented
- Suggest they check the changelog or contact the dev team
```

### Sales Pre-Qualification Agent

```text theme={null}
You are a sales assistant for [Company Name].

Your goals:
- Answer questions about our products and pricing
- Help visitors understand which solution fits their needs
- Qualify leads by understanding their requirements

Guidelines:
- Be enthusiastic but not pushy
- Ask clarifying questions to understand needs
- Highlight relevant features based on their use case

For pricing questions:
- Provide general pricing tiers if available
- Encourage scheduling a demo for detailed quotes
- Offer to connect them with a sales representative
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="Changes not reflecting in preview">
    The preview widget may use cached responses. Try:

    1. Refresh the page
    2. Clear the conversation in the widget
    3. Ask a completely new question
  </Accordion>

  <Accordion icon="floppy-disk" title="Save button stays disabled">
    The Save button only enables when changes are detected. Ensure you've actually modified the text, not just clicked in the textarea.
  </Accordion>

  <Accordion icon="list-check" title="Template not loading">
    If templates don't appear in the selector:

    1. Refresh the page
    2. Check your internet connection
    3. Contact support if the issue persists
  </Accordion>

  <Accordion icon="robot" title="Agent gives incorrect responses">
    If responses are inaccurate:

    1. Check that your knowledge base contains the relevant information
    2. Review your system prompt for conflicting instructions
    3. Try being more specific in your prompt about response accuracy
    4. Add relevant Q\&A sources for common questions
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Add Knowledge Sources" icon="database" href="/sources/overview">
    Expand your agent's knowledge by adding more web pages, text, and Q\&A content.
  </Card>

  <Card title="Customize Appearance" icon="palette" href="/customization/styling">
    Match your agent's visual style to your brand with colors, backgrounds, and widget settings.
  </Card>

  <Card title="Deploy to Website" icon="code" href="/agents/deployment">
    Learn how to embed your agent on your live website.
  </Card>

  <Card title="View Conversations" icon="messages" href="/agents/conversations">
    Monitor how users interact with your deployed agent.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.cosmo.humanizing.com/changelog

Recent updates and improvements to Cosmo by Humanizing

# Changelog

Stay up to date with the latest features, improvements, and fixes.

## May 2026

### Widget Context Placeholders for Chatbot Prompts

<Badge>New</Badge>

Chat widget prompts can now use page and custom context placeholders, so one agent can adapt to different pages, locations, departments, or campaigns without duplicating the agent.

**Highlights:**

* Built-in placeholders for `{{ page_url }}`, `{{ page_origin }}`, and `{{ page_path }}`
* Custom context values can be passed through `humanizing.init("YOUR_PUBLIC_KEY", { context: { ... } })`
* Prompt authors add placeholders in **Playground → Instructions (System prompt)**
* Full setup is documented in [Widget Context](/chat-widget/context)

***

## April 2026

### Billing Is Now Live — Subscribe to Unlock Full Access

<Badge>New</Badge>

Cosmo by Humanizing now has a full Stripe-powered billing system, so you can subscribe to a plan directly within the platform and manage everything from your workspace settings.

**Highlights:**

* Choose a plan and subscribe with a credit card via Stripe Checkout
* Active subscription status is visible in workspace billing settings
* Free trial period available before a paid plan is required
* Billing management (invoices, payment method, cancellation) accessible from the billing portal

***

### Extended Free Trial: 14 Days and 5,000 Credits

<Badge>New</Badge>

The free trial has been extended to 14 days with a 5,000-credit allowance — up from 7 days and 100 credits — with no credit card required.

**Highlights:**

* Trial duration doubled from 7 to 14 days
* Credit allowance increased from 100 to 5,000 — enough to meaningfully evaluate the platform
* No credit card required at signup; upgrade manually when your trial ends
* Trial expiry reminder emails sent before the trial ends

***

### Voicebot Is Included in Multi-Channel Packages

<Badge>New</Badge>

After your free trial ends, Voicebot remains available in Standard, Pro, Large, and Enterprise packages.

**Highlights:**

* Voicebot remains fully accessible during the free trial period
* Hobby remains the Chatbot-only package
* Upgrading to Standard or higher unlocks Voicebot for your workspace

***

### Self-Service Phone Number Provisioning

<Badge>New</Badge>

You can now search, purchase, and manage phone numbers directly from the Cosmo — no separate Twilio account required — at a fraction of the previous cost.

**Highlights:**

* Search available numbers by country and area code from within the app
* Purchase a number with one click; it is automatically registered and ready to assign
* Phone numbers are managed at the workspace level and can be assigned across Voicebot agents
* Significantly lower cost vs. previous provider

***

### Per-Minute Credit Usage for Voicebot

<Badge>New</Badge>

Voicebot usage now consumes 100 credits per started minute from the allowance included in your package.

**Highlights:**

* Call minutes are tracked and converted to credits automatically
* Usage is visible in your workspace billing dashboard
* There is no separate Voicebot per-minute line item

***

### Kiosk Avatar Calls Now Consume Credits

<Badge>New</Badge>

Kiosk Avatar voice calls are now metered using your credit balance at a rate of 50 credits per started minute, keeping usage consistent with the Chatbot and Voicebot billing model.

**Highlights:**

* 50 credits are charged at the start of each call minute
* If your credit balance runs out mid-call, the call ends gracefully
* Credit consumption appears in the usage dashboard alongside Chatbot and Voicebot consumption

***

### Unified Agent Architecture

<Badge>New</Badge>

Agents are now a single unified entity with channels you enable per agent, replacing the previous separate setup model — and the voice agent is now called Voicebot everywhere in the platform.

**Highlights:**

* One agent with three channels: Chatbot, Voicebot, and Kiosk Avatar
* Enable only the channels your use case requires
* "Call" / "Caller" references renamed to "Voicebot" across the platform for clarity

***

### Visitors Can Now Rate AI Responses With Thumbs Up / Thumbs Down

<Badge>New</Badge>

Chat widget visitors can now rate individual AI responses, giving you direct quality signals and helping you identify which answers need improvement.

**Highlights:**

* Thumbs up / thumbs down buttons appear on each agent message in the chat widget
* Feedback counts visible in the Analytics dashboard
* Helps measure response quality and surface training data signals

***

### Text Chat Mode in Voicebot Playground

<Badge>New</Badge>

The Voicebot playground now includes a text chat input so you can test your agent's responses by typing — no microphone needed.

**Highlights:**

* Type messages directly in the playground to test knowledge base and RAG responses
* Agent replies appear as text in a chat panel alongside audio playback
* Ideal for quickly reproducing specific queries or testing without a microphone

***

### Analytics Pages Now Show Real Data

<Badge>Improvement</Badge>

The Kiosk Avatar, Chatbot, and Voicebot analytics pages have been fully wired to live backend data — mock stats and "Coming Soon" placeholders have been replaced with real metrics.

**Highlights:**

* Kiosk Avatar analytics: real call volume, answered/missed/average duration stats
* Chat analytics: real total conversations, average rating, unique sessions, and charts
* Date range filtering now works across all analytics pages

***

### Save With an Annual Plan

<Badge>New</Badge>

You can now choose between monthly and yearly billing when subscribing, with yearly plans offered at a discounted rate compared to paying month-to-month.

**Highlights:**

* Toggle between monthly and yearly billing during checkout
* Yearly plans offer a discount versus the monthly equivalent
* Billing cycle is shown on your subscription details page

***

### Upgrade or Downgrade Your Plan Anytime

<Badge>New</Badge>

You can now switch between subscription plans directly from the billing settings — upgrade to unlock more features or downgrade to a lower tier without needing to cancel and resubscribe.

**Highlights:**

* Upgrade and downgrade options available in workspace billing settings
* Plan changes take effect immediately (upgrades) or at the end of the billing period (downgrades)

***

### Set Your Agent's Default Language at Creation Time

<Badge>Improvement</Badge>

You can now choose the default conversation language for your agent directly in the creation modal and onboarding flow, so agents greet visitors in the right language from day one.

**Highlights:**

* Language selector added to the blank agent creation modal
* Language selection step added to the Chatbot onboarding flow
* App UI language and agent conversation language remain independent settings

***

### Help & Support Now Accessible From the Sidebar

<Badge>New</Badge>

A new Help section is available under Settings in both the workspace sidebar and the agent detail sidebar, giving you a quick way to report bugs or request features without leaving the app.

**Highlights:**

* "Report a Bug" and "Request a Feature" entry points in both sidebars
* Support form accepts rich context including screenshots and file attachments
* Submissions routed directly to the Humanizing support team

***

## February 2026

### Kiosk Avatar — Kiosk-Based Reception System

<Badge>New</Badge>

The Kiosk Avatar is a channel designed for physical reception desks and lobbies. It runs as a full-screen kiosk on a tablet or screen, greets visitors with a 3D avatar, and lets them register their arrival or reach the right contact by voice.

**Highlights:**

* Full-screen kiosk mode deployable on any tablet or display
* Guided onboarding to configure name, avatar, contacts, and styling
* Visitor call logs with contact name, timestamp, duration, and status
* Contacts management to route visitors to the right person

***

### Visitor Feedback on AI Responses

<Badge>New</Badge>

Chat widget visitors can rate individual AI responses with thumbs up or thumbs down, giving you direct signals on which answers are helpful and which need improvement.

**Highlights:**

* Feedback buttons on every agent message
* Feedback counts visible in analytics
* Idempotent toggle — clicking the same rating removes it


# Widget Context
Source: https://docs.cosmo.humanizing.com/chat-widget/context

Personalize chat widget prompts with page and custom context placeholders

## Overview

Widget context lets one Chatbot adapt to the page or location where it is embedded. The widget sends context values with each chat request, and your agent uses them only when you reference them in the system prompt with placeholders such as `{{ page_path }}` or `{{ location }}`.

Use widget context when the same agent is embedded across multiple pages, branches, departments, or customer locations and needs to answer with the right local details.

<Note>
  Context values are data, not instructions. They do not change your agent unless your saved prompt contains a matching placeholder.
</Note>

## Where to Configure It

<Steps>
  <Step title="Add placeholders in the Playground">
    Open your agent in the dashboard, go to **Playground**, and edit **Instructions (System prompt)**. Add placeholders with double curly braces, for example `{{ location }}`.
  </Step>

  <Step title="Pass context in the embed code">
    Go to **Deploy → Chat Widget**, copy the embed code, and add a `context` object to `humanizing.init`.
  </Step>

  <Step title="Test on the embedded page">
    Visit the page where the widget is installed, start a conversation, and confirm the agent responds with the page or custom value.
  </Step>
</Steps>

## Built-In Page Context

The embed script automatically sends these values from the current page. For example, if a visitor opens `https://example.com/products/widget?utm_source=newsletter#details`, the widget sends:

| Placeholder         | Example                               | Description                                   |
| ------------------- | ------------------------------------- | --------------------------------------------- |
| `{{ page_url }}`    | `https://example.com/products/widget` | Current page URL without query string or hash |
| `{{ page_origin }}` | `https://example.com`                 | Site origin, including protocol and domain    |
| `{{ page_path }}`   | `/products/widget`                    | Current path on the site                      |

For single-page applications, the widget refreshes this page context when the browser URL changes.

### Prompt Example

Add this in **Playground → Instructions (System prompt)**:

```text theme={null}
The visitor is currently on {{ page_path }}.
If their question is page-specific, use that page as the first clue for what they need.
```

Then embed the widget with the standard snippet:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>humanizing.init("YOUR_PUBLIC_KEY");</script>
```

## Custom Context

You can also pass your own context values as the second argument to `humanizing.init`.

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch",
      department: "Service",
      premiumCustomer: true
    }
  });
</script>
```

Then reference those values in the system prompt:

```text theme={null}
You are answering for the {{ location }} location.
If a visitor asks about appointments, route them to the {{ department }} team.
```

At request time, the agent receives:

```text theme={null}
You are answering for the North Branch location.
If a visitor asks about appointments, route them to the Service team.
```

<Tip>
  Use custom context for values that are known by your website, such as branch, market, product line, campaign, customer segment, or language variant.
</Tip>

## Rules and Limits

| Rule                 | Details                                                                |
| -------------------- | ---------------------------------------------------------------------- |
| Placeholder format   | Use `{{ key }}` in the system prompt                                   |
| Key format           | Start with a letter, then use letters, numbers, or underscores         |
| Values               | Strings, numbers, and booleans are supported                           |
| Maximum keys         | Up to 50 context keys are accepted                                     |
| Maximum value length | Values are limited to 500 characters                                   |
| Missing values       | If a key is not provided, the placeholder stays visible as `{{ key }}` |

<Warning>
  Do not put instructions, secrets, access tokens, or private customer data in widget context. The embed code runs in the visitor's browser and should only contain data that is safe to expose on that page.
</Warning>

## Common Patterns

### Multi-Location Agent

Use the same agent for multiple branches:

```html theme={null}
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch",
      phone: "+49 241 000000"
    }
  });
</script>
```

```text theme={null}
You are answering for our {{ location }} branch.
When visitors ask how to reach us by phone, give them {{ phone }}.
```

### Page-Aware Support

Let the agent know which page the visitor is viewing:

```text theme={null}
The visitor is chatting from {{ page_url }}.
Use the current page as context, but answer only from the knowledge base.
```

### Different Departments

Reuse one agent across different department pages:

```html theme={null}
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      department: "Sales"
    }
  });
</script>
```

```text theme={null}
You are currently supporting the {{ department }} department.
If the question belongs to another department, explain who can help.
```

## Troubleshooting

<AccordionGroup>
  <Accordion icon="brackets-curly" title="The placeholder appears in the answer">
    Check that the key in your prompt exactly matches the key in your context object. For example, `{{ location }}` only resolves when the embed sends `context: { location: "North Branch" }`.
  </Accordion>

  <Accordion icon="code" title="My custom value is ignored">
    Make sure the value is a string, number, or boolean. Objects, arrays, null values, and keys that start with an underscore are ignored.
  </Accordion>

  <Accordion icon="route" title="The page path is outdated">
    In most single-page applications, the widget refreshes page context after route changes. If your framework changes content without changing the browser URL, pass a custom context value when initializing or updating the widget.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Edit Prompts" icon="flask" href="/agents/playground">
    Add placeholders to your agent instructions.
  </Card>

  <Card title="Embed the Widget" icon="code" href="/chat-widget/embedding">
    Add context to your widget snippet.
  </Card>
</CardGroup>


# Embedding the Widget
Source: https://docs.cosmo.humanizing.com/chat-widget/embedding

Step-by-step guide to embedding the chat widget on your website

## Getting Your Embed Code

The embed code is available from your agents deployment page in the Cosmo dashboard.

<Steps>
  <Step title="Navigate to Your Agent">
    Open your agent from the Agents list in your workspace.
  </Step>

  <Step title="Go to Deployment">
    Click on the **Deployment** tab in the agent settings.
  </Step>

  <Step title="Copy the Embed Code">
    Copy the JavaScript snippet provided.
  </Step>
</Steps>

## Basic Embedding

Add the following script to your website, typically just before the closing body tag:

```html theme={null}
<script
  src="https://chat.humanizing.com/embed.js"
  data-agent-id="YOUR_AGENT_ID"
  async
></script>
```

<Warning>
  Replace YOUR\_AGENT\_ID with your actual agent ID from the dashboard.
</Warning>

## Embedding Methods

### Method 1: Script Tag (Recommended)

The simplest method - works with any website:

```html theme={null}
<\!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <\!-- Your website content -->

  <\!-- Chat Widget (place before closing body) -->
  <script
    src="https://chat.humanizing.com/embed.js"
    data-agent-id="YOUR_AGENT_ID"
    async
  ></script>
</body>
</html>
```

### Method 2: Dynamic Loading

Load the widget after page load for better performance:

```javascript theme={null}
window.addEventListener("load", function() {
  const script = document.createElement("script");
  script.src = "https://chat.humanizing.com/embed.js";
  script.setAttribute("data-agent-id", "YOUR_AGENT_ID");
  script.async = true;
  document.body.appendChild(script);
});
```

## Configuration Options

Configure the widget behavior using data attributes:

| Attribute         | Type    | Description                                          |
| ----------------- | ------- | ---------------------------------------------------- |
| data-agent-id     | string  | **Required.** Your agent ID from the dashboard       |
| data-position     | string  | Widget position: bottom-right (default), bottom-left |
| data-open-on-load | boolean | Auto-open widget when page loads                     |
| data-hide-button  | boolean | Hide the floating chat button                        |

## Page and Custom Context

The widget can send page context and custom values with each chat request. Use this when one agent should adapt to the page, location, department, or campaign where it is embedded.

The embed script automatically provides these prompt placeholders:

| Placeholder         | Description                                   |
| ------------------- | --------------------------------------------- |
| `{{ page_url }}`    | Current page URL without query string or hash |
| `{{ page_origin }}` | Current site origin                           |
| `{{ page_path }}`   | Current path on the site                      |

For example, on `https://example.com/products/widget?utm_source=newsletter#details`, `{{ page_url }}` is `https://example.com/products/widget`, `{{ page_origin }}` is `https://example.com`, and `{{ page_path }}` is `/products/widget`.

To pass your own values, add a `context` object to `humanizing.init`:

```html theme={null}
<script src="https://chat.humanizing.com/embed.js"></script>
<script>
  humanizing.init("YOUR_PUBLIC_KEY", {
    context: {
      location: "North Branch",
      department: "Service"
    }
  });
</script>
```

Then add matching placeholders in **Playground → Instructions (System prompt)**:

```text theme={null}
You are answering for the {{ location }} location.
If the visitor asks about appointments, route them to the {{ department }} team.
```

<Card title="Widget Context Guide" icon="brackets-curly" href="/chat-widget/context">
  Learn where to add prompt placeholders, which built-in values are available, and how custom context is validated.
</Card>

## Verifying Your Installation

After adding the embed code:

1. **Clear your cache** - Ensure you are seeing the latest version of your site
2. **Look for the chat button** - A floating button should appear in the corner
3. **Click to open** - The chat interface should open smoothly
4. **Test a conversation** - Send a test message to verify the connection

<Tip>
  Use your browser developer tools (F12) to check for any JavaScript errors if the widget does not appear.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-exclamation" title="Widget not appearing">
    * Verify the agent ID is correct
    * Check that your agent is deployed (not in draft mode)
    * Ensure no JavaScript errors in the console
    * Check for CSS conflicts with z-index
  </Accordion>

  <Accordion icon="ban" title="CORS or network errors">
    * Verify your domain is allowed in agent settings
    * Check that your site uses HTTPS
    * Ensure no ad blockers are interfering
  </Accordion>

  <Accordion icon="mobile-screen" title="Mobile display issues">
    * The widget is designed to be responsive
    * Avatar panel is hidden on mobile (expected behavior)
    * Check viewport meta tag is present
  </Accordion>

  <Accordion icon="clipboard" title="Copy button not working">
    If clicking the copy button does nothing, your browser may be blocking clipboard access.

    * Ensure the site is loaded over **HTTPS**
    * Check that your browser has not blocked clipboard permissions for this site (look for the permissions icon in the address bar)
    * As a fallback, manually select the code and use **Ctrl+C** / **Cmd+C** to copy
  </Accordion>
</AccordionGroup>

## Security Considerations

<Note>
  The widget only works on domains you have authorized in your agent settings. Unauthorized domains will see a connection error.
</Note>

* Always use HTTPS on your website
* Keep your agent ID confidential (though it is visible in page source)
* Configure allowed domains in the dashboard

## Next Steps

<CardGroup>
  <Card title="User Features" icon="sparkles" href="/chat-widget/user-features">
    Learn about features available to your visitors.
  </Card>

  <Card title="Widget Settings" icon="sliders" href="/customization/widget">
    Configure welcome messages and questions.
  </Card>

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

  <Card title="Analytics" icon="chart-bar" href="/agents/analytics">
    Track widget usage and conversations.
  </Card>
</CardGroup>


# Chat Widget Overview
Source: https://docs.cosmo.humanizing.com/chat-widget/overview

Introduction to the Cosmo Chatbot widget - an embeddable AI-powered chat interface with 3D avatar support

## What is the Chat Widget?

The Chat Widget is an embeddable AI-powered chat interface that you can add to any website. It provides your visitors with instant access to a conversational AI assistant trained on your knowledge base.

## Key Features

<CardGroup>
  <Card title="AI-Powered Conversations" icon="robot">
    Natural language conversations powered by your custom-trained AI agent.
  </Card>

  <Card title="3D Avatar" icon="user-robot">
    Interactive animated character with lip-sync for spoken responses.
  </Card>

  <Card title="Multi-Language Support" icon="globe">
    Support for multiple languages with real-time translation.
  </Card>

  <Card title="Customizable Design" icon="palette">
    Match your brand colors, fonts, and styling.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Create Your Agent">
    Set up an AI agent in your workspace and configure its personality and knowledge base.
  </Step>

  <Step title="Add Knowledge Sources">
    Train your agent with website content, documents, Q\&A pairs, or custom text.
  </Step>

  <Step title="Customize Appearance">
    Configure the widgets colors, avatar, welcome message, and suggested questions.
  </Step>

  <Step title="Embed on Your Website">
    Copy the embed code and add it to your website to make your agent live.
  </Step>
</Steps>

## Widget Components

The chat widget consists of several components that work together:

| Component             | Description                                          |
| --------------------- | ---------------------------------------------------- |
| **Chat Button**       | Floating button that visitors click to open the chat |
| **Chat Panel**        | Main conversation area with message input            |
| **Avatar Panel**      | 3D animated character (desktop only)                 |
| **Language Selector** | Interface for switching languages                    |
| **Header Controls**   | Reset, language, and avatar toggle buttons           |

## Platform Support

| Platform             | Support Level                              |
| -------------------- | ------------------------------------------ |
| **Desktop Browsers** | Full support including 3D avatar and audio |
| **Mobile Browsers**  | Full chat experience, no avatar panel      |
| **Tablets**          | Responsive design adapts to screen size    |

<Note>
  The 3D avatar panel is optimized for desktop screens (800px+ width) to ensure the best visual experience and performance.
</Note>

## Next Steps

<CardGroup>
  <Card title="Embedding Guide" icon="code" href="/chat-widget/embedding">
    Learn how to add the widget to your website.
  </Card>

  <Card title="User Features" icon="sparkles" href="/chat-widget/user-features">
    Explore the interactive features available to visitors.
  </Card>

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

  <Card title="Widget Settings" icon="sliders" href="/customization/widget">
    Configure welcome messages and questions.
  </Card>
</CardGroup>


# User Features
Source: https://docs.cosmo.humanizing.com/chat-widget/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>
  <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>
  <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>


# Localization & Language
Source: https://docs.cosmo.humanizing.com/customization/localization

Configure language settings to serve international visitors with a multilingual chat experience

## Overview

Localization settings allow you to configure which languages your chat widget supports and set a default language for visitors. This enables you to create a multilingual chat experience that serves international audiences in their preferred language.

<Tip>
  The chat widget automatically adapts its interface text based on the visitor's browser language if that language is enabled. Visitors can also manually switch languages within the widget.
</Tip>

## Accessing Localization Settings

1. Navigate to your agent in the dashboard
2. Click on **Deploy** in the sidebar
3. Select **Chat Widget** to access the settings
4. Scroll to the **Localization** section

The localization settings display your current configuration including the default language and the number of enabled languages.

## Default Language

<Tip>
  You can also set the default language when first creating an agent. The creation modal and onboarding wizard both include a language selector so your agent is configured correctly from the start.
</Tip>

The default language is the primary language your chat widget displays when:

* A visitor's browser language is not in your enabled languages list
* The visitor hasn't selected a language preference
* The widget first loads for new visitors

### Changing the Default Language

1. Click the **Manage** button in the Localization section
2. In the language selection modal, hover over your desired language
3. Click **Make Default** to set it as the primary language
4. Click **Save** to apply changes

<Note>
  The default language is always enabled and cannot be disabled. If you want to change the default, first make another language the default, then you can disable the previous one if needed.
</Note>

## Managing Enabled Languages

Control which languages are available to your visitors by enabling or disabling specific languages.

### Opening the Language Manager

Click the **Manage** button in the Localization section to open the language selection modal.

### Enabling Languages

In the language selection modal:

1. Browse or search for languages using the search field
2. Check the checkbox next to each language you want to enable
3. Use **Select All** to enable all filtered languages at once
4. Click **Save** to apply your changes

### Disabling Languages

1. Uncheck the checkbox next to languages you want to disable
2. Use **Deselect All** to disable all filtered languages (except the default)
3. Click **Save** to apply your changes

<Warning>
  Disabling languages removes them from the language selector in the chat widget. Visitors using a disabled language will be switched to the default language.
</Warning>

## Supported Languages

The platform supports over 40 languages covering major regions worldwide:

<AccordionGroup>
  <Accordion icon="globe-americas" title="Americas">
    | Language                | Code     |
    | ----------------------- | -------- |
    | English                 | `en`     |
    | Spanish                 | `es`     |
    | Spanish (Latin America) | `es-419` |
    | Portuguese (Brazil)     | `pt-BR`  |
    | Portuguese              | `pt`     |
  </Accordion>

  <Accordion icon="globe-europe" title="Europe">
    | Language   | Code    |
    | ---------- | ------- |
    | German     | `de`    |
    | French     | `fr`    |
    | Italian    | `it`    |
    | Dutch      | `nl`    |
    | Polish     | `pl`    |
    | Romanian   | `ro`    |
    | Czech      | `cs`    |
    | Hungarian  | `hu`    |
    | Slovak     | `sk`    |
    | Slovenian  | `sl`    |
    | Croatian   | `hr`    |
    | Serbian    | `sr`    |
    | Bosnian    | `bs`    |
    | Bulgarian  | `bg`    |
    | Greek      | `el`    |
    | Albanian   | `sq-AL` |
    | Ukrainian  | `uk`    |
    | Russian    | `ru`    |
    | Swedish    | `sv`    |
    | Norwegian  | `no`    |
    | Danish     | `da`    |
    | Finnish    | `fi`    |
    | Estonian   | `et`    |
    | Latvian    | `lv`    |
    | Lithuanian | `lt`    |
  </Accordion>

  <Accordion icon="globe-asia" title="Asia & Middle East">
    | Language              | Code    |
    | --------------------- | ------- |
    | Chinese (Simplified)  | `zh-CN` |
    | Chinese (Traditional) | `zh-TW` |
    | Japanese              | `ja`    |
    | Korean                | `ko`    |
    | Hindi                 | `hi`    |
    | Tamil (India)         | `ta-IN` |
    | Thai                  | `th`    |
    | Vietnamese            | `vi`    |
    | Indonesian            | `id`    |
    | Malay                 | `ms`    |
    | Arabic (UAE)          | `ar-AE` |
    | Arabic (Saudi Arabia) | `ar-SA` |
    | Hebrew                | `he`    |
    | Persian               | `fa`    |
    | Turkish               | `tr`    |
  </Accordion>
</AccordionGroup>

## How Language Affects the Widget

When a visitor uses the chat widget, language settings affect several elements:

| Element               | Behavior                                                                              |
| --------------------- | ------------------------------------------------------------------------------------- |
| **Interface text**    | Buttons, placeholders, and system messages display in the selected language           |
| **Welcome message**   | Shown in the configured default language (customize per language in Content settings) |
| **AI responses**      | The agent responds in the same language the visitor uses                              |
| **Language selector** | Only enabled languages appear in the dropdown                                         |

### Visitor Language Detection

The widget uses this priority to determine the initial language:

<Steps>
  <Step title="Browser language">
    If the visitor's browser language matches an enabled language, the widget uses it automatically.
  </Step>

  <Step title="Previous selection">
    If the visitor previously selected a language, the widget remembers their preference.
  </Step>

  <Step title="Default fallback">
    If no match is found, the widget displays in your configured default language.
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Enable relevant languages only">
    Only enable languages for regions you actively serve. Having too many options can overwhelm visitors and may not provide a good experience if your knowledge base doesn't cover those languages well.
  </Accordion>

  <Accordion icon="book" title="Ensure knowledge base coverage">
    Before enabling a language, ensure your knowledge sources have content in that language or that your agent can effectively translate and respond in that language.
  </Accordion>

  <Accordion icon="users" title="Match your audience">
    Analyze your website traffic to identify which languages your visitors use most frequently. Prioritize enabling those languages.
  </Accordion>

  <Accordion icon="message" title="Set appropriate default">
    Choose a default language that matches your primary audience. This ensures the best first impression for most visitors.
  </Accordion>

  <Accordion icon="globe" title="Test in each language">
    Use the [Playground](/agents/playground) to test conversations in each enabled language. Verify the agent responds appropriately and the experience is consistent.
  </Accordion>
</AccordionGroup>

## Configuration Reference

### Default Values

| Setting           | Default Value         |
| ----------------- | --------------------- |
| Default Language  | English (`en`)        |
| Enabled Languages | All languages enabled |

### Localization Settings Summary

| Setting               | Description                                                           |
| --------------------- | --------------------------------------------------------------------- |
| **Default Language**  | The primary language shown when no matching visitor language is found |
| **Enabled Languages** | Languages available for selection in the chat widget                  |

## Next Steps

<CardGroup>
  <Card title="Widget Configuration" icon="sliders" href="/customization/widget">
    Configure welcome messages and suggested questions for your enabled languages.
  </Card>

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

  <Card title="Test in Playground" icon="flask" href="/agents/playground">
    Test your agent's multilingual responses before going live.
  </Card>

  <Card title="Deploy Your Widget" icon="code" href="/agents/deployment">
    Get the embed code and add your localized widget to your website.
  </Card>
</CardGroup>


# Styling & Appearance
Source: https://docs.cosmo.humanizing.com/customization/styling

Customize your agent's visual appearance with avatars, colors, backgrounds, and themes to match your brand

## Overview

The Styling settings let you customize how your chat widget looks and feels on your website. You can adjust everything from the avatar character to colors, themes, and widget positioning to create a seamless brand experience for your visitors.

<Tip>
  All styling changes can be previewed in real-time before saving. Use the live preview panel to see exactly how your widget will appear to visitors.
</Tip>

## Accessing Styling Settings

1. Navigate to your agent in the dashboard
2. Click on **Deploy** in the sidebar
3. Select **Chat Widget** to access the styling options

The styling options are organized into the **Styling** tab, while content options like welcome messages and suggested questions are in the **Content** tab.

## Avatar

Your agent's avatar is the visual representation that appears in the chat widget. It creates a more engaging, human-like experience for visitors.

### Selecting an Avatar

| Option                  | Description                                                 |
| ----------------------- | ----------------------------------------------------------- |
| **Choose from library** | Select from a collection of pre-made 3D avatar characters   |
| **Change anytime**      | You can switch avatars at any time from the widget settings |

To select or change an avatar:

1. Click the **Change** button (or **Select** if no avatar is set)
2. Browse the avatar gallery
3. Click on an avatar to preview it
4. Click **Select** to confirm your choice

<Note>
  Avatars animate and can speak responses using text-to-speech, creating a more interactive experience for your visitors.
</Note>

### Avatar Background

You can customize the background behind your avatar:

| Setting               | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| **Custom Background** | Enable to set a custom background color                                               |
| **Background Color**  | Choose any color using the color picker or enter a hex code                           |
| **Transparency**      | Adjust the background transparency from 0% (fully transparent) to 100% (fully opaque) |

## Appearance

Choose between light and dark themes for your chat widget to match your website's design.

### Theme Options

<CardGroup>
  <Card title="Light Theme" icon="sun">
    A bright, clean appearance with light backgrounds and dark text. Best for websites with light color schemes.
  </Card>

  <Card title="Dark Theme" icon="moon">
    A darker appearance with dark backgrounds and light text. Ideal for websites with dark color schemes or for reducing eye strain.
  </Card>
</CardGroup>

To change the theme:

1. Navigate to the **Styling** tab
2. Under **Appearance**, click on either the **Light** or **Dark** card
3. The selected theme will be highlighted with a border

## Brand Color

The brand color is your primary color that appears throughout the widget. It's used for:

* Send button
* Active elements and highlights
* Links and interactive components
* Primary action buttons

### Setting Your Brand Color

1. Click on the color swatch to open the color picker
2. Select your desired color, or
3. Enter a hex color code directly (e.g., `#171717`)
4. Click the reset icon to restore the default color

<Tip>
  Choose a brand color that matches your website's primary color for a cohesive look. Ensure sufficient contrast for accessibility.
</Tip>

## Color Overrides

Fine-tune specific elements of your widget with individual color overrides. Each override can be enabled or disabled independently.

### Available Color Overrides

| Color Setting           | What It Affects                               | Default   |
| ----------------------- | --------------------------------------------- | --------- |
| **User Message Color**  | Background color of messages sent by visitors | `#171717` |
| **Widget Header Color** | Background color of the widget header bar     | `#171717` |
| **Bubble Color**        | Background color of the chat bubble button    | `#171717` |
| **Hint Background**     | Background color of hint/tooltip elements     | `#171717` |

### Configuring Color Overrides

For each color override:

1. Toggle the switch to **enable** the override
2. Click the color swatch to open the color picker
3. Select your color or enter a hex code
4. Use the reset button to restore the default value

<Note>
  When a color override is disabled, the widget uses the default color automatically. Enable overrides only when you need custom colors.
</Note>

## Chat Bubble

The chat bubble is the floating button visitors click to open the chat widget. Customize its position and appearance.

### Bubble Position

Choose where the chat bubble appears on your website:

| Position  | Description                                         |
| --------- | --------------------------------------------------- |
| **Left**  | Bubble appears in the bottom-left corner            |
| **Right** | Bubble appears in the bottom-right corner (default) |

### Custom Chat Icon

Replace the default chat icon with your own:

1. Toggle **Chat Icon** to enable custom icon
2. Click **Upload** to select an image from your device
3. Supported formats: PNG, JPG, SVG
4. Recommended size: 48x48 pixels or larger

<Warning>
  When you disable the custom icon toggle, the widget reverts to the default chat icon.
</Warning>

## Saving Your Changes

After making styling changes:

1. Review your changes in the live preview panel
2. Click **Save Changes** when satisfied
3. The widget on your website will update automatically

If you navigate away with unsaved changes, you'll be prompted to save or discard them.

### Discarding Changes

Click **Discard** to revert all changes back to the last saved state. This is useful if you want to start over or made changes you don't want to keep.

## Best Practices

<AccordionGroup>
  <Accordion icon="palette" title="Match your brand">
    Use your website's primary colors for the brand color and overrides. Consistent colors create a professional, integrated experience.
  </Accordion>

  <Accordion icon="eye" title="Test both themes">
    Preview your widget in both light and dark themes to ensure it looks good regardless of user preferences or website design.
  </Accordion>

  <Accordion icon="universal-access" title="Consider accessibility">
    Choose colors with sufficient contrast ratios. Avoid low-contrast combinations that make text difficult to read.
  </Accordion>

  <Accordion icon="location-dot" title="Position thoughtfully">
    Place the chat bubble where it won't obstruct important content. The bottom-right corner is conventional, but left positioning works well for some layouts.
  </Accordion>

  <Accordion icon="mobile" title="Check mobile appearance">
    Test your styling on mobile devices. The widget should look good and be easy to use on smaller screens.
  </Accordion>
</AccordionGroup>

## Styling Reference

### Default Values

| Setting                        | Default Value |
| ------------------------------ | ------------- |
| Appearance                     | Light         |
| Brand Color                    | `#171717`     |
| User Message Color             | `#171717`     |
| Widget Header Color            | `#171717`     |
| Bubble Color                   | `#171717`     |
| Hint Background                | `#171717`     |
| Bubble Position                | Right         |
| Avatar Background Color        | `#FFFFFF`     |
| Avatar Background Transparency | 70%           |

### Color Format

All colors use hexadecimal format:

```
#RRGGBB

Examples:
- #171717 (dark gray - default)
- #FFFFFF (white)
- #3B82F6 (blue)
- #10B981 (green)
- #EF4444 (red)
```

## Next Steps

<CardGroup>
  <Card title="Widget Configuration" icon="sliders" href="/customization/widget">
    Configure widget content like welcome messages and suggested questions.
  </Card>

  <Card title="Localization" icon="globe" href="/customization/localization">
    Set up language options for international visitors.
  </Card>

  <Card title="Deploy Your Widget" icon="code" href="/agents/deployment">
    Get the embed code and add your styled widget to your website.
  </Card>

  <Card title="Test in Playground" icon="flask" href="/agents/playground">
    Test your agent's responses before going live.
  </Card>
</CardGroup>


# Widget Configuration
Source: https://docs.cosmo.humanizing.com/customization/widget

Configure your chat widget's content, messages, and behavior settings

## Overview

The Widget Configuration settings control what your chat widget displays and how it behaves when visitors interact with it. This includes the welcome message, header title, suggested questions, and the chat bubble's position and icon.

<Tip>
  Widget configuration works alongside [Styling](/customization/styling) settings. Use styling to control appearance (colors, themes) and widget configuration to control content and behavior.
</Tip>

## Accessing Widget Settings

1. Navigate to your agent in the dashboard
2. Click on **Deploy** in the sidebar
3. Select **Chat Widget** to access the configuration options

The widget settings are organized across two main areas:

* **Styling tab** - Visual appearance (covered in [Styling documentation](/customization/styling))
* **Content tab** - Messages, prompts, and text content (covered here)

## Chat Bubble Position

The chat bubble is the floating button visitors click to open your chat widget. You can position it on either side of the screen.

### Position Options

| Position  | Description                                         |
| --------- | --------------------------------------------------- |
| **Right** | Bubble appears in the bottom-right corner (default) |
| **Left**  | Bubble appears in the bottom-left corner            |

### Choosing a Position

Consider these factors when selecting bubble position:

<AccordionGroup>
  <Accordion icon="window-maximize" title="Website layout">
    If your website has important content or navigation on one side, place the bubble on the opposite side to avoid obstruction.
  </Accordion>

  <Accordion icon="comment" title="Existing chat tools">
    If you have other chat tools or support widgets, position your bubble away from them to avoid confusion.
  </Accordion>

  <Accordion icon="hand-pointer" title="Call-to-action buttons">
    Avoid placing the bubble near other floating elements like scroll-to-top buttons or promotional banners.
  </Accordion>

  <Accordion icon="mobile-screen" title="Mobile considerations">
    Test both positions on mobile devices. The bottom-right is conventional, but left positioning may work better for some mobile layouts.
  </Accordion>
</AccordionGroup>

To change the position:

1. Navigate to the **Styling** tab in Chat Widget settings
2. Scroll to the **Chat Bubble** section
3. Select either **Left** or **Right** position
4. Preview the change in the live preview panel
5. Click **Save Changes**

## Custom Chat Icon

Replace the default chat bubble icon with your own custom image to match your brand.

### Enabling Custom Icon

1. Navigate to the **Styling** tab
2. Find the **Chat Bubble** section
3. Toggle **Chat Icon** to enable custom icon upload
4. Click **Upload** to select an image from your device

### Icon Requirements

| Requirement          | Specification                     |
| -------------------- | --------------------------------- |
| **Formats**          | PNG, JPG, SVG                     |
| **Recommended size** | 48x48 pixels or larger            |
| **Aspect ratio**     | Square (1:1) recommended          |
| **File size**        | Keep under 100KB for fast loading |

<Warning>
  When you disable the custom icon toggle, the widget reverts to the default chat icon. Your uploaded image is preserved and will reappear if you re-enable the toggle.
</Warning>

### Icon Best Practices

* Use a simple, recognizable icon that works at small sizes
* Ensure the icon has good contrast against the bubble background color
* Test your icon on both light and dark website backgrounds
* Consider using your logo or a custom chat-related icon

## Header Title

The header title appears at the top of the chat widget when it's open. It helps visitors understand who or what they're chatting with.

### Setting the Header Title

1. Navigate to the **Content** tab in Chat Widget settings
2. Find the **Header Title** field
3. Enter your desired title (e.g., "Chat with Support", "Ask Our Assistant")
4. Save your changes

### Header Title Examples

| Use Case         | Example Title             |
| ---------------- | ------------------------- |
| Customer support | "Support Chat"            |
| Sales assistant  | "Talk to Sales"           |
| General help     | "How can we help?"        |
| Brand-focused    | "Chat with \[Brand Name]" |
| Product-specific | "\[Product] Assistant"    |

<Note>
  If no header title is set, the widget will display a default title. Setting a custom title creates a more personalized experience for visitors.
</Note>

## Welcome Message

The welcome message is the first thing visitors see when they open the chat widget. It sets the tone for the conversation and helps visitors understand how to get started.

### Configuring the Welcome Message

1. Navigate to the **Content** tab
2. Find the **Welcome Message** field
3. Enter your message in the text area
4. Preview how it appears in the live preview
5. Save your changes

### Writing Effective Welcome Messages

<CardGroup>
  <Card title="Be friendly" icon="face-smile">
    Use a warm, approachable tone that makes visitors feel comfortable asking questions.
  </Card>

  <Card title="Be clear" icon="bullseye">
    Let visitors know what kind of help they can expect and what topics the agent can assist with.
  </Card>

  <Card title="Be brief" icon="compress">
    Keep the message concise. Long welcome messages can be overwhelming and may get skipped.
  </Card>

  <Card title="Be actionable" icon="hand-pointer">
    Encourage visitors to ask their first question or guide them toward common topics.
  </Card>
</CardGroup>

### Welcome Message Examples

**Customer Support:**

```
Hi there! I'm here to help you with any questions about your account, orders, or our products. What can I assist you with today?
```

**Sales Assistant:**

```
Welcome! I can help you find the right solution for your needs. Feel free to ask about pricing, features, or request a demo.
```

**Documentation Helper:**

```
Hello! I can help you navigate our documentation and answer technical questions. What would you like to know?
```

## Suggested Messages

Suggested messages (also called quick replies or starter prompts) appear as clickable buttons that visitors can use to quickly start a conversation. They reduce friction and help visitors who may not know what to ask.

### Adding Suggested Messages

1. Navigate to the **Content** tab
2. Find the **Suggested Messages** section
3. Click **Add** to create a new suggested message
4. Enter the message text
5. Repeat for additional messages
6. Drag to reorder if needed
7. Save your changes

### Managing Suggested Messages

| Action      | How To                                                |
| ----------- | ----------------------------------------------------- |
| **Add**     | Click the **Add** button and enter your message       |
| **Edit**    | Click on an existing message to modify the text       |
| **Remove**  | Click the **X** button next to a message to delete it |
| **Reorder** | Drag and drop messages to change their display order  |

### Best Practices for Suggested Messages

<Steps>
  <Step title="Limit the number">
    Use 2-4 suggested messages. Too many options can overwhelm visitors and have the opposite effect of what you intend.
  </Step>

  <Step title="Cover common topics">
    Choose messages that address your most frequently asked questions or common visitor needs.
  </Step>

  <Step title="Keep them short">
    Suggested messages should be brief and scannable - ideally under 50 characters.
  </Step>

  <Step title="Make them actionable">
    Phrase messages as questions or requests that the agent can respond to directly.
  </Step>
</Steps>

### Suggested Message Examples

**E-commerce:**

* "What are your shipping options?"
* "How do I return an item?"
* "Track my order"
* "Talk to a human"

**SaaS Product:**

* "What features are included?"
* "How does pricing work?"
* "See a demo"
* "Get help with my account"

**Support Portal:**

* "Reset my password"
* "Billing questions"
* "Technical support"
* "Feature request"

## Configuration Reference

### Default Values

| Setting              | Default Value          |
| -------------------- | ---------------------- |
| Chat Bubble Position | Right                  |
| Custom Icon          | Disabled               |
| Header Title         | Not set (uses default) |
| Welcome Message      | Not set (uses default) |
| Suggested Messages   | Empty                  |

### Character Limits

| Field             | Recommended Limit  |
| ----------------- | ------------------ |
| Header Title      | 30 characters      |
| Welcome Message   | 200 characters     |
| Suggested Message | 50 characters each |

<Note>
  These are recommended limits for optimal display. Longer text may be truncated or cause layout issues on smaller screens.
</Note>

## Preview and Testing

Always preview your widget configuration changes before saving:

1. Make your changes in the configuration panel
2. Watch the live preview on the right side of the screen
3. Test on both desktop and mobile views if available
4. Click **Save Changes** when satisfied

<Tip>
  Use the [Playground](/agents/playground) to test how your agent responds to the suggested messages and verify the conversational flow works well with your configured welcome message.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Styling & Appearance" icon="palette" href="/customization/styling">
    Customize colors, themes, and visual appearance of your widget.
  </Card>

  <Card title="Localization" icon="globe" href="/customization/localization">
    Configure language settings for international visitors.
  </Card>

  <Card title="Deploy Your Widget" icon="code" href="/agents/deployment">
    Get the embed code and add your configured widget to your website.
  </Card>

  <Card title="Conversations" icon="messages" href="/agents/conversations">
    Monitor chat conversations and visitor interactions.
  </Card>
</CardGroup>


# Request an AVV (DPA)
Source: https://docs.cosmo.humanizing.com/data-protection/avv

Request the current Cosmo data processing agreement from Humanizing

The Auftragsverarbeitungsvertrag (AVV), also called a Data Processing Agreement (DPA), governs how Humanizing processes customer content and end-user personal data on your organization's behalf.

<Warning>
  The Cosmo B2B Terms and Web App Privacy Notice do not by themselves conclude an AVV. The AVV is provided and concluded separately.
</Warning>

## How to request it

Humanizing provides the AVV at registration or contract conclusion before processing starts. Paid customers can also request the current version at any time. If you need it before a paid order, request it during procurement.

Email [contact@humanizing.com](mailto:contact@humanizing.com?subject=DPA%20%28AVV%29%20request%20-%20%5BCompany%20name%5D) with this subject:

```text theme={null}
DPA (AVV) request - [Company name]
```

Include:

* Your organization's full legal name and address
* The name and role of the contact person
* The email address used for your Cosmo account or order, if available
* Any procurement deadline or signature requirement

<Card title="Request the AVV" icon="envelope" href="mailto:contact@humanizing.com?subject=DPA%20%28AVV%29%20request%20-%20%5BCompany%20name%5D">
  Email [contact@humanizing.com](mailto:contact@humanizing.com) to request the current agreement.
</Card>

## When it is required

Conclude the AVV before Cosmo starts processing customer content or end-user personal data for your organization. Use the current version supplied by Humanizing rather than an older saved copy.

The AVV covers the processing relationship, technical and organizational measures, deletion and return, and the applicable subprocessor provisions. Your organization must still provide its own end-user privacy notice and determine its purposes, legal bases, and retention rules.

<CardGroup>
  <Card title="Data Protection & GDPR" icon="shield-check" href="/data-protection/overview">
    Review the role split and the information processed by each Cosmo channel.
  </Card>

  <Card title="Privacy Notice Template" icon="file-lines" href="/data-protection/privacy-notice-template">
    Prepare information for your Chatbot, Voicebot, and Kiosk Avatar users.
  </Card>
</CardGroup>


# Data Protection & GDPR
Source: https://docs.cosmo.humanizing.com/data-protection/overview

Understand GDPR roles, customer content, and data processing across Cosmo's Voicebot, Chatbot, and Kiosk Avatar

Use this section to prepare a compliant Cosmo deployment. It explains which legal document applies, which information each channel can process, and what your organization must complete before going live.

<Note>
  This documentation is an operational starting point, not legal advice. Your organization must assess its purposes, legal bases, retention periods, notices, and any sector-specific requirements.
</Note>

## Which document applies?

| Processing context                                                                                | GDPR role                                                        | Relevant document                                                                           |
| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Cosmo account, administrator, billing, and support data                                           | Humanizing is the controller                                     | [Cosmo Web App Privacy Notice](https://cosmo.humanizing.com/web-app-privacy)                |
| Prompts, knowledge sources, integrations, and end-user interactions handled for your organization | Your organization is the controller; Humanizing is the processor | Your organization's privacy notice and the separately concluded [AVV](/data-protection/avv) |
| Contract terms and customer responsibilities                                                      | Defined in the Cosmo B2B Terms                                   | [Cosmo B2B Terms](https://cosmo.humanizing.com/terms)                                       |

The Web App Privacy Notice covers the business users who create, administer, pay for, or request support for a Cosmo account. It does not replace the privacy notice that you provide to people who interact with your agent.

## Data processing by channel

Use this table as a review checklist. Confirm each category against your live configuration and current AVV before you publish your notice.

| Channel                   | Categories to verify for your configuration                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Voicebot**              | Voice input, transcripts, generated replies and speech, call time and duration, and any enabled recording or routing data.       |
| **Chatbot**               | Chat messages, generated replies, timestamps, and information that an end user enters in the conversation.                       |
| **Kiosk Avatar**          | Information submitted through enabled touch, voice, language, visit, contact-search, call, or notification features.             |
| **Shared technical data** | Session identifiers, agent and language settings, and technical information recorded to provide and protect the enabled service. |

Your prompts, knowledge sources, uploaded documents, integration data, conversations, calls, and transcripts are customer content. Humanizing processes this content for your organization under the AVV.

## Before you go live

<Steps>
  <Step title="Conclude the AVV">
    Conclude the AVV before Cosmo processes customer content or end-user personal data for your organization. [Request the current AVV](/data-protection/avv).
  </Step>

  <Step title="Document your processing">
    Define the purpose, legal basis, data categories, recipients, retention period, and deletion process for your actual configuration.
  </Step>

  <Step title="Inform end users">
    Clearly state that the person is interacting with an AI system. Make your privacy notice available at each relevant interface. Start with the [privacy notice template](/data-protection/privacy-notice-template).
  </Step>

  <Step title="Check Voicebot requirements">
    Assess the rules that apply to telephone services, call recording, consent, caller identification, and emergency communications. Do not describe a call as recorded unless recording is enabled and your organization has established a lawful process.
  </Step>

  <Step title="Verify the live experience">
    Test the final notice, links, opening message, enabled channels, and retention settings in the deployed experience.
  </Step>
</Steps>

## Public legal documents

<CardGroup>
  <Card title="Web App Privacy Notice" icon="user-shield" href="https://cosmo.humanizing.com/web-app-privacy">
    How Humanizing processes Cosmo account, administration, billing, and support data.
  </Card>

  <Card title="B2B Terms" icon="file-contract" href="https://cosmo.humanizing.com/terms">
    Contract terms, customer duties, and the separate AVV requirement.
  </Card>
</CardGroup>


# Privacy Notice Template
Source: https://docs.cosmo.humanizing.com/data-protection/privacy-notice-template

Adapt a GDPR privacy notice for Cosmo Voicebot, Chatbot, and Kiosk Avatar deployments

Adapt this template to your actual processing. Remove channels and data categories that you do not use. Add the optional features that you enable. Include the final text in your full privacy notice.

<Warning>
  This template is not a complete privacy notice and does not determine your legal basis or retention period. Have the final notice reviewed for your organization, use case, and jurisdiction.
</Warning>

## Full template

```text theme={null}
Use of our Cosmo AI assistant

Controller: [ORGANIZATION], [ADDRESS AND CONTACT DETAILS]
Data protection contact: [CONTACT DETAILS]
Full privacy notice: [FULL PRIVACY-NOTICE URL]

We use the Cosmo AI assistant to [PURPOSE]. You are interacting with an AI system.

For each enabled channel, include only the categories that your actual configuration processes:

- Voicebot: [VOICE INPUT, TRANSCRIPTS, GENERATED REPLIES OR SPEECH, CALL TIME AND DURATION, AND ANY ENABLED RECORDING OR ROUTING DATA.]
- Chatbot: [CHAT MESSAGES, GENERATED REPLIES, TIMESTAMPS, AND INFORMATION ENTERED IN THE CONVERSATION.]
- Kiosk Avatar: [INFORMATION FROM ENABLED TOUCH, VOICE, LANGUAGE, VISIT, CONTACT-SEARCH, CALL, OR NOTIFICATION FEATURES.]
- Shared technical information: [SESSION IDENTIFIERS, LANGUAGE SETTINGS, AND TECHNICAL INFORMATION RECORDED TO PROVIDE AND PROTECT THE ENABLED SERVICE.]

We process this information for [PURPOSE]. The legal basis is [LEGAL BASIS]. We retain the information for [RETENTION PERIOD OR CRITERIA].

[ORGANIZATION] is the controller for this processing. We use Humanizing Technologies GmbH, In der Trift 1, 57462 Olpe, Germany, as our processor to provide and operate Cosmo on our behalf.

Recipients and transfers: [DESCRIBE THE RECIPIENTS AND ANY INTERNATIONAL TRANSFERS THAT APPLY TO YOUR CONFIGURATION, USING THE CURRENT AVV AND SUBPROCESSOR INFORMATION.]

For complete information about this processing, retention, recipients, transfers, and your rights, see our full privacy notice at [FULL PRIVACY-NOTICE URL].
```

## Short notice at the interface

Use a short notice where the interaction starts and link it to your full privacy notice.

```text theme={null}
You are interacting with our AI assistant. We process the information you provide to answer your request. See [PRIVACY-NOTICE URL] for details.
```

For a Voicebot, include this information in or immediately around the opening message. If calls are recorded, add a separate accurate recording notice and any consent flow required for your use case.

## Deployment checklist

* The controller name and contact details identify your organization, not Humanizing.
* Only enabled channels and features are described.
* The notice states the actual purpose, legal basis, and retention period.
* Voicebot wording matches the live recording, transcription, call, and routing configuration.
* The full privacy notice is available at every relevant interface.
* End users are clearly told that they are interacting with an AI system.
* The AVV has been concluded before processing begins.

<Card title="Request an AVV" icon="file-signature" href="/data-protection/avv">
  Request the current data processing agreement from Humanizing.
</Card>


# Authentication
Source: https://docs.cosmo.humanizing.com/getting-started/authentication

Learn how to sign up, sign in, and manage your account access

## Overview

Cosmo by Humanizing provides secure authentication to protect your account and workspaces. You can sign in using email and password, a passwordless magic link, or try the platform anonymously.

## Sign Up

Create a new account to get started with Cosmo by Humanizing.

<Steps>
  <Step title="Navigate to Sign Up">
    Go to the **Sign Up** page or click "Sign up" from the sign-in page.
  </Step>

  <Step title="Enter Your Details">
    Fill in the registration form:

    * **Full Name** - Your display name in the platform
    * **Email** - A valid email address for verification
    * **Password** - At least 8 characters
    * **Confirm Password** - Re-enter your password to confirm
  </Step>

  <Step title="Create Your Account">
    Click **Sign Up** to create your account. You'll be redirected to a verification pending screen — check your email inbox for a verification link.
  </Step>

  <Step title="Verify Your Email">
    Click the verification link in your email to confirm your address. You will not be able to access the dashboard until your email is verified. If you don't see the email, check your spam folder or use the **Resend** button on the verification screen.
  </Step>
</Steps>

<Note>
  Your password must be at least 8 characters long. Make sure both password fields match exactly.
</Note>

### Invitation Sign Up

If you've been invited to join a workspace, you'll receive an email with a special invitation link:

1. Click the invitation link in your email
2. If you don't have an account, you'll be directed to sign up with your email pre-filled
3. Complete the sign-up form
4. After signing up, you'll automatically join the workspace

## Sign In

Access your account using one of three authentication methods.

### Password Sign In

The default method using your email and password:

<Steps>
  <Step title="Go to Sign In">
    Navigate to the **Sign In** page.
  </Step>

  <Step title="Select Password Tab">
    Click the **Password** tab (selected by default).
  </Step>

  <Step title="Enter Credentials">
    Enter your registered **Email** address and **Password**.
  </Step>

  <Step title="Sign In">
    Click **Sign In** to access your account. You'll be redirected to your dashboard or agents page.
  </Step>
</Steps>

<Tip>
  If you've forgotten your password, click the **Forgot password?** link below the form.
</Tip>

### Magic Link Sign In

For passwordless authentication, use the magic link option:

<Steps>
  <Step title="Select Magic Link Tab">
    On the sign-in page, click the **Magic Link** tab.
  </Step>

  <Step title="Enter Your Email">
    Enter the email address associated with your account.
  </Step>

  <Step title="Send Magic Link">
    Click **Send Magic Link**. You'll see a confirmation message.
  </Step>

  <Step title="Check Your Email">
    Open your email and click the magic link to sign in instantly. The link will redirect you to your dashboard.
  </Step>
</Steps>

<Note>
  Magic links are single-use and expire after a short period. If your link doesn't work, request a new one.
</Note>

### Anonymous Sign In

Try the platform without creating a full account:

<Steps>
  <Step title="Select Anonymous Tab">
    On the sign-in page, click the **Anonymous** tab.
  </Step>

  <Step title="Continue Anonymously">
    Click **Continue Anonymously** to create a temporary session.
  </Step>
</Steps>

Anonymous sessions allow you to explore the platform before committing to registration. You can link your anonymous session to a full account later.

## Password Reset

If you've forgotten your password, you can reset it:

<Steps>
  <Step title="Go to Forgot Password">
    On the sign-in page, click **Forgot password?** to access the password reset page.
  </Step>

  <Step title="Enter Your Email">
    Enter your registered email address.
  </Step>

  <Step title="Request Reset Link">
    Click **Send Reset Link**. You'll see a confirmation screen telling you to check your email — you are not redirected back to the sign-in page. If an account with that email exists, a password reset email will be sent.
  </Step>

  <Step title="Check Your Email">
    Open the password reset email and click the reset link.
  </Step>

  <Step title="Set New Password">
    Enter your new password (at least 8 characters) and confirm it. Click **Reset Password** to save.
  </Step>
</Steps>

<Warning>
  Password reset links expire after a limited time for security. If your link has expired, request a new one.
</Warning>

## Protected Routes

Certain pages require authentication to access. If you try to visit these pages without being signed in, you'll be automatically redirected to the sign-in page.

| Route         | Description                        |
| ------------- | ---------------------------------- |
| `/dashboard`  | Your main workspace overview       |
| `/agents`     | Agent management and configuration |
| `/onboarding` | New agent creation wizard          |
| `/settings`   | Account and workspace settings     |

After signing in, you'll be redirected back to your intended destination.

## Session Management

Your session remains active until you sign out or it expires. For security:

* Sessions are stored securely as HTTP-only cookies
* You can sign out from any page using the account menu
* Signing in from a new device creates a new session

## Troubleshooting

<AccordionGroup>
  <Accordion icon="circle-xmark" title="Passwords don't match error">
    Make sure both the Password and Confirm Password fields contain exactly the same value. Passwords are case-sensitive.
  </Accordion>

  <Accordion icon="lock" title="Password too short error">
    Your password must be at least 8 characters long. Try a longer password that combines letters, numbers, and symbols.
  </Accordion>

  <Accordion icon="envelope" title="Magic link not received">
    Check your spam or junk folder. If the email still doesn't arrive after a few minutes, verify that you entered the correct email address and try again.
  </Accordion>

  <Accordion icon="user-xmark" title="Account not found for magic link">
    Magic links only work for existing accounts. If you don't have an account yet, use the Sign Up page to create one first.
  </Accordion>

  <Accordion icon="key" title="Password reset link expired">
    Password reset links expire for security reasons. Request a new reset link from the forgot password page.
  </Accordion>

  <Accordion icon="circle-exclamation" title="Email not verified error">
    Check your email inbox for a verification link. Click it to verify your email, then try signing in again.
  </Accordion>

  <Accordion icon="right-to-bracket" title="Can't access protected pages">
    Protected pages require authentication. Sign in first, then try accessing the page again.
  </Accordion>

  <Accordion icon="user-check" title="Email already registered">
    If you see "This email is already registered", an account with that address already exists. Click **Sign In** in the notification or navigate to the sign-in page to access your account. Use **Forgot password?** if you don't remember your password.
  </Accordion>

  <Accordion icon="circle-xmark" title="Invalid credentials error">
    If you see "Wrong email or password. Please try again.", double-check your email and password. Use the **Forgot password?** link to reset if needed.
  </Accordion>

  <Accordion icon="clock" title="Account temporarily locked">
    After multiple failed login attempts, your account may be temporarily locked. Wait a few minutes before trying again.
  </Accordion>

  <Accordion icon="envelope-open" title="Email not yet verified">
    If you see a message about verifying your email, check your inbox for the verification link and click it before signing in.
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup>
  <Card title="Use Strong Passwords" icon="lock">
    Create passwords with at least 8 characters. Use a mix of letters, numbers, and symbols.
  </Card>

  <Card title="Keep Email Secure" icon="envelope">
    Your email is used for password resets and magic links. Keep your email account secure.
  </Card>

  <Card title="Don't Share Credentials" icon="user-shield">
    Never share your password or magic links. Use workspace invitations for team access.
  </Card>

  <Card title="Sign Out When Done" icon="right-from-bracket">
    Always sign out when using shared or public computers.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Create Workspace" icon="briefcase" href="/getting-started/create-workspace">
    Set up your first workspace after signing in.
  </Card>

  <Card title="Create Agent" icon="robot" href="/agents/overview">
    Learn how to create your first AI agent.
  </Card>
</CardGroup>


# Create a Workspace
Source: https://docs.cosmo.humanizing.com/getting-started/create-workspace

Learn how to create and manage workspaces to organize your AI agents and team members

## Overview

Workspaces are the foundation for organizing your AI agents and collaborating with team members in Cosmo by Humanizing. Each workspace contains its own agents, knowledge sources, and team members with defined roles.

## What is a Workspace?

A workspace is an isolated environment that contains:

* **AI Agents** - Your configured chat agents with their knowledge bases
* **Team Members** - Collaborators with different permission levels
* **Settings** - Workspace-specific configuration and preferences

<Info>
  You can create multiple workspaces to separate different projects, clients, or departments. Each workspace operates independently with its own agents and team.
</Info>

## Creating Your First Workspace

When you sign up for Cosmo by Humanizing, you'll be prompted to create your first workspace.

### Steps to create a workspace

1. Navigate to the **Create Workspace** page
2. Enter your **Workspace Name** (required)
   * Choose a descriptive name that reflects the purpose (e.g., "Marketing Team", "Customer Support", "Acme Corp")
   * Names can be between 2-100 characters
3. Click **Create Workspace**

<Tip>
  A unique identifier (slug) is automatically generated from your workspace name. This is used internally for routing and API calls.
</Tip>

### After creating a workspace

Once your workspace is created:

* It becomes your **active workspace**
* You're automatically set as the **owner** with full permissions
* You'll be redirected to the agents page where you can create your first AI agent

## Switching Between Workspaces

If you have access to multiple workspaces, you can easily switch between them:

1. Click on the **workspace name** in the top navigation
2. Click the **dropdown arrow** to open the workspace selector
3. Use the search field to find a specific workspace (optional)
4. Click on the workspace you want to switch to

<Note>
  When switching workspaces, you'll be redirected to the agents list of the selected workspace. Each workspace has its own separate set of agents and data.
</Note>

## Creating Additional Workspaces

You can create new workspaces at any time:

1. Click on the **workspace dropdown** in the navigation
2. Click **Create Workspace** at the bottom of the dropdown
3. Fill in the workspace details
4. Optionally invite team members during creation
5. Click **Create Workspace**

## Workspace Roles

Each workspace has a role-based permission system:

| Role       | Description                                                                            |
| ---------- | -------------------------------------------------------------------------------------- |
| **Owner**  | Full access to all workspace features, can delete the workspace and manage all members |
| **Admin**  | Can manage agents, sources, and invite new members                                     |
| **Member** | Can view and interact with agents but has limited management capabilities              |

<Warning>
  Only owners can delete a workspace. This action is permanent and removes all agents, sources, and data associated with the workspace.
</Warning>

## Workspace Settings

Once created, you can manage your workspace through the settings:

* **Rename** - Update the workspace display name
* **Team Members** - Invite, manage, or remove team members
* **Delete** - Permanently remove the workspace (owner only)

To access workspace settings:

1. Navigate to **Settings** in the sidebar
2. Select **Workspace** for general settings
3. Select **Members** to manage team access

## Best Practices

<AccordionGroup>
  <Accordion icon="sitemap" title="Organize by project or team">
    Create separate workspaces for different projects, clients, or departments. This keeps data isolated and makes it easier to manage permissions.
  </Accordion>

  <Accordion icon="users" title="Invite team members early">
    Add collaborators to your workspace so they can help build and maintain agents. Use appropriate roles based on their responsibilities.
  </Accordion>

  <Accordion icon="shield-check" title="Use descriptive names">
    Choose workspace names that clearly indicate their purpose. This helps when switching between multiple workspaces.
  </Accordion>

  <Accordion icon="arrow-right-arrow-left" title="Keep workspaces focused">
    Rather than putting all agents in one workspace, consider creating dedicated workspaces for different use cases to maintain organization.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Create Your First Agent" icon="robot" href="/agents/overview">
    Learn how to create and configure an AI agent.
  </Card>

  <Card title="Invite Team Members" icon="user-plus" href="/workspace/members">
    Add collaborators to your workspace.
  </Card>
</CardGroup>


# Welcome to Cosmo by Humanizing
Source: https://docs.cosmo.humanizing.com/index

Set up one AI agent for your website, phone, and front desk

## What is Cosmo by Humanizing?

Cosmo by Humanizing is your AI receptionist for the places visitors reach you most: your phone line, website, and front desk. One AI agent uses your knowledge base across three channels: Voicebot, Chatbot, and Kiosk Avatar.

<Card title="Get started in 5 minutes" icon="rocket" href="/getting-started/authentication">
  Create your first AI agent and turn on the channels your team needs.
</Card>

## Key Features

<Columns>
  <Card title="Voicebot" icon="phone" href="/voicebot/overview">
    Pick up calls, answer common questions, route conversations, and capture notes.
  </Card>

  <Card title="Chatbot" icon="robot" href="/agents/overview">
    Answer website visitors instantly with a brand-aware chat widget trained on your content.
  </Card>

  <Card title="Kiosk Avatar" icon="building" href="/receptionist/overview">
    Welcome guests on a kiosk with a 3D avatar, contact search, and visitor flow.
  </Card>

  <Card title="Knowledge Sources" icon="database" href="/sources/overview">
    Train one shared AI agent on web pages, custom text, and Q\&A pairs.
  </Card>
</Columns>

## How It Works

<Steps>
  <Step title="Create a Workspace">
    Sign up and create a workspace where your team manages Cosmo.
  </Step>

  <Step title="Build Your AI Agent">
    Go through the guided onboarding to set up your domain, import content, and choose an avatar.
  </Step>

  <Step title="Add Knowledge Sources">
    Import website content, add custom text, or create Q\&A pairs so Cosmo can answer accurately.
  </Step>

  <Step title="Turn On Channels">
    Connect the Voicebot, deploy the Chatbot, or open the Kiosk Avatar on a kiosk.
  </Step>
</Steps>

## Quick Links

<Columns>
  <Card title="Authentication" icon="key" href="/getting-started/authentication">
    Sign up and log in to the platform.
  </Card>

  <Card title="Chatbot Onboarding" icon="sparkles" href="/agents/onboarding">
    Step-by-step guide to creating your website Chatbot.
  </Card>

  <Card title="Kiosk Avatar" icon="building" href="/receptionist/overview">
    Set up an AI-powered front desk experience.
  </Card>
</Columns>

## Need Help?

<Card title="Contact Support" icon="envelope" href="mailto:support@humanizing.dev">
  Our team is here to help you get the most out of Cosmo by Humanizing.
</Card>


# Getting Started
Source: https://docs.cosmo.humanizing.com/quickstart

Set up Cosmo and deploy your first channel in under 10 minutes

## Welcome to Cosmo by Humanizing

This guide walks you through setting up Cosmo as your AI receptionist. You will create one AI agent, add knowledge, and deploy your first channel. Start with the Voicebot, Chatbot, or Kiosk Avatar based on your use case.

<Note>
  **Prerequisites**: You'll need content for Cosmo to learn from, such as web pages, text, or FAQs. If you are starting with the Chatbot, you will also need the website where you want to deploy it.
</Note>

## Quick Start Overview

<Steps>
  <Step title="Create Your Account">
    Sign up for Cosmo by Humanizing and create your first workspace.
  </Step>

  <Step title="Set Up Your AI Agent">
    Go through the guided onboarding to configure your domain, branding, avatar, and knowledge.
  </Step>

  <Step title="Add Knowledge">
    Import your website content, add custom text, or create Q\&A pairs.
  </Step>

  <Step title="Deploy a Channel">
    Connect the Voicebot, turn on the Chatbot, or launch the Kiosk Avatar.
  </Step>
</Steps>

## Step 1: Create Your Account

<Accordion title="Sign up and create a workspace" icon="user-plus">
  1. Go to [app.cosmo.humanizing.com](https://app.cosmo.humanizing.com) and click **Sign Up**
  2. Enter your email address and create a password
  3. Verify your email address by clicking the link we send you
  4. Create your first workspace by entering a name for your team or project

  <Tip>
    Workspaces help you organize agents by project, client, or team. You can create multiple workspaces and invite team members.
  </Tip>
</Accordion>

For detailed authentication options including magic link sign-in and password reset, see [Authentication](/getting-started/authentication).

## Step 2: Set Up Your AI Agent

Once you're logged in, you'll be guided through the setup process:

<AccordionGroup>
  <Accordion title="Enter your website domain" icon="globe">
    Start by entering your website's domain (e.g., `yourdomain.com`). This helps us:

    * Fetch available pages to import as knowledge sources
    * Detect your brand colors and logo automatically
    * Configure Cosmo's identity
  </Accordion>

  <Accordion title="Select pages to import" icon="file-lines">
    We'll discover pages from your website. Select which ones contain content you want Cosmo to know about:

    * Product pages
    * FAQ sections
    * Help documentation
    * About pages

    <Tip>Focus on content that answers common visitor questions. You can always add more sources later.</Tip>
  </Accordion>

  <Accordion title="Choose your avatar" icon="user">
    Select a 3D avatar to represent Cosmo. The avatar:

    * Speaks and animates during conversations
    * Creates a more engaging experience for visitors
    * Can be customized to match your brand
  </Accordion>

  <Accordion title="Wait for content ingestion" icon="spinner">
    Your selected pages will be processed and indexed. This usually takes 1-2 minutes depending on the amount of content.
  </Accordion>
</AccordionGroup>

For complete details on the Chatbot setup flow, see [Chatbot Onboarding](/agents/onboarding).

## Step 3: Add Knowledge Sources

Cosmo learns from three types of knowledge sources:

<CardGroup>
  <Card title="Web Sources" icon="globe" href="/sources/web-sources">
    Import content from your website pages, sitemaps, or crawl entire sections.
  </Card>

  <Card title="Text Sources" icon="file-lines" href="/sources/text-sources">
    Add custom text content like product descriptions, policies, or internal documentation.
  </Card>

  <Card title="Q&A Sources" icon="message-question" href="/sources/qa-sources">
    Create specific question-answer pairs for FAQs and common queries.
  </Card>
</CardGroup>

<Note>
  The more relevant content you add, the better Cosmo will be at answering visitor questions. Start with your most frequently asked questions and expand from there.
</Note>

## Step 4: Deploy the Chatbot

Once your AI agent is configured, deploying the Chatbot is simple:

<Steps>
  <Step title="Go to Deployment">
    Navigate to your agent's **Deployment** tab in the Cosmo dashboard.
  </Step>

  <Step title="Copy the embed script">
    Copy the generated script tag:

    ```html theme={null}
    <script
      src="https://chat.humanizing.com/embed.js"
      data-agent-id="your-agent-id"
      async
    ></script>
    ```
  </Step>

  <Step title="Add to your website">
    Paste the script before the closing `</body>` tag on every page where you want the chat widget to appear.
  </Step>

  <Step title="Verify it's working">
    Visit your website and look for the chat widget icon in the corner. Click it to start a conversation!
  </Step>
</Steps>

For complete deployment options and customization, see [Deployment](/agents/deployment).

## Next Steps

Now that your first channel is live, explore these features:

<Columns>
  <Card title="Customize Appearance" icon="palette" href="/customization/styling">
    Match Cosmo's look to your brand with colors, backgrounds, and styling options.
  </Card>

  <Card title="Test in Playground" icon="flask" href="/agents/playground">
    Try different prompts and templates to fine-tune Cosmo's responses.
  </Card>

  <Card title="View Conversations" icon="comments" href="/agents/conversations">
    Monitor what visitors are asking and how Cosmo responds.
  </Card>

  <Card title="Analyze Performance" icon="chart-line" href="/agents/analytics">
    Track usage metrics and understand how visitors interact with Cosmo.
  </Card>
</Columns>

## Need Help?

<Card title="Contact Support" icon="envelope" href="mailto:support@humanizing.dev">
  Our team is here to help you get the most out of Cosmo by Humanizing. Reach out anytime!
</Card>


# Analytics
Source: https://docs.cosmo.humanizing.com/receptionist/analytics

Monitor Kiosk Avatar performance with call metrics and a full visitor log

## Overview

The Analytics page shows live call data for your Kiosk Avatar. Use it to track how many visitors are being connected, spot missed call patterns, and review individual visit records over any date range.

<Tip>
  Filter by date range to compare activity across weeks or months and identify usage trends.
</Tip>

***

## Stats Cards

Five summary cards are displayed at the top of the page:

| Card                 | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| **Total Calls**      | All calls initiated through the kiosk during the selected period  |
| **Answered**         | Calls that were successfully connected to a contact               |
| **Missed**           | Calls where no contact was reached                                |
| **Average Duration** | Mean call length across all answered calls in the selected period |
| **Answer Rate**      | Percentage of total calls that were answered                      |

<Note>
  If your agent has no call data yet, the stats cards and visitor log will show an empty state. Make a test call from the kiosk to generate your first data points.
</Note>

***

## Visitor Log

Below the stats cards is a table listing every call attempt. Each row represents one visitor interaction.

| Column           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| **Contact Name** | The employee the visitor selected from the directory |
| **Timestamp**    | Date and time the call was initiated                 |
| **Duration**     | Length of the call (blank for missed calls)          |
| **Status**       | Whether the call was **Answered** or **Missed**      |

### Call Statuses

* **Answered** — the contact picked up and the call connected successfully
* **Missed** — the call was not answered (contact unavailable, declined, or timed out)

***

## Filtering by Date Range

Use the date range picker in the toolbar to narrow the data shown in both the stats cards and the visitor log.

1. Click the date range picker at the top of the Analytics page.
2. Select a start date and an end date.
3. The stats cards and visitor log update immediately to reflect the selected period.

<Tip>
  To review a specific event or busy day, pick a single-day range. To see a monthly summary, select the first and last day of the month.
</Tip>

***

## Credit Consumption

Each Kiosk Avatar call consumes credits based on call time:

* **50 credits per started minute** of call time
* If your credit balance reaches zero mid-call, the call ends gracefully

Monitor your credit usage alongside call volume to forecast when you may need to top up your balance.

<Note>
  Credit consumption is tracked at the workspace level. Visit the **Usage** page in the main sidebar for a full breakdown across all agents.
</Note>

***

## Next Steps

<CardGroup>
  <Card title="Manage Contacts" icon="address-book" href="/receptionist/contacts">
    Keep your employee directory up to date so visitors can reach the right people.
  </Card>

  <Card title="Kiosk Deployment" icon="rocket" href="/receptionist/deployment">
    Review deployment options and device setup for the kiosk.
  </Card>

  <Card title="Kiosk Avatar Overview" icon="robot" href="/receptionist/overview">
    Learn how the Kiosk Avatar works end to end.
  </Card>

  <Card title="Workspace Usage" icon="chart-mixed" href="/agents/analytics">
    View credit consumption and aggregated metrics across all agents.
  </Card>
</CardGroup>


# Managing Contacts
Source: https://docs.cosmo.humanizing.com/receptionist/contacts

Import and manage the employee contact directory for your Kiosk Avatar

## Overview

The Contacts page manages the employee directory that visitors can search through on the kiosk. Visitors use the contact search screen to find people by name, phone, or email, and then initiate a call or notification.

## Accessing Contacts

Navigate to your Kiosk Avatar in the sidebar. **Contacts** is listed as the second item under the Kiosk Avatar section, after Playground & Setup. The page has two tabs:

| Tab             | Purpose                                          |
| --------------- | ------------------------------------------------ |
| **My Contacts** | View, search, edit, and delete existing contacts |
| **Add New**     | Add contacts manually or import via CSV          |

***

## Viewing Contacts

The **My Contacts** tab displays all contacts in a data table with:

* **Name** — Full name of the employee
* **Phone** — Phone number
* **Email** — Email address
* **Actions** — Edit and delete buttons

### Searching

Use the search bar above the table to filter contacts by name, phone, or email. Search is instant and case-insensitive.

### Bulk Actions

Select multiple contacts using checkboxes (shift-click for range selection) to perform bulk actions:

* **Delete selected** — Remove multiple contacts at once

***

## Adding Contacts

Switch to the **Add New** tab to add contacts. Three methods are available:

### Manual Entry

Fill in the contact form:

1. Enter the **Name** (required)
2. Enter the **Phone** number (optional)
3. Enter the **Email** address (optional)
4. Click **Add Contact**

### CSV Import

Import contacts from a CSV file:

1. Click **Import CSV**
2. Upload a CSV file or paste CSV data into the text area
3. The expected format is: `name,phone,email` (one contact per line)
4. Review the parsed contacts
5. Click **Import** to add them

<Note>
  The CSV parser handles quoted fields correctly (e.g., `"Smith, John","+1234567890","john@example.com"`), so names with commas work as expected.
</Note>

### Example Contacts

Click **Add 3 Example Contacts** to quickly populate the directory with sample data for testing.

***

## Editing Contacts

Click the **edit icon** (pencil) in the Actions column to edit a contact. Update any field and save changes.

## Deleting Contacts

Click the **delete icon** (trash) in the Actions column to remove a single contact. For bulk deletion, use checkboxes and the bulk actions bar.

***

## Best Practices

<AccordionGroup>
  <Accordion icon="file-csv" title="Keep contact data clean">
    Regularly review and update contacts. Remove employees who have left and add new ones promptly. Visitors rely on this directory to find the right person.
  </Accordion>

  <Accordion icon="phone" title="Include phone numbers">
    While phone and email are optional, including at least a phone number for each contact enables the full calling flow on the kiosk.
  </Accordion>

  <Accordion icon="magnifying-glass" title="Use full names">
    Enter full names (first and last) to make search results more accurate. Avoid abbreviations or nicknames that visitors might not recognize.
  </Accordion>

  <Accordion icon="upload" title="Use CSV for bulk imports">
    If you have more than a few contacts, export them from your HR system or directory as CSV and import them. This is much faster than manual entry.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Customize Kiosk Styling" icon="palette" href="/receptionist/styling">
    Configure the visual appearance of your kiosk.
  </Card>

  <Card title="Deploy Your Kiosk" icon="rocket" href="/receptionist/deployment">
    Get the deployment URL and set up your physical kiosk device.
  </Card>
</CardGroup>


# Kiosk Deployment
Source: https://docs.cosmo.humanizing.com/receptionist/deployment

Deploy your Kiosk Avatar to a tablet or touchscreen device

## Overview

Deploying the Kiosk Avatar is straightforward — open a URL on any device with a web browser. No app installation or embed code required.

## Getting the Kiosk URL

1. Navigate to your Kiosk Avatar's **Playground** page
2. The **Deploy Kiosk** section is displayed at the top of the Playground page for quick access — no scrolling required.
3. Copy the kiosk URL:

```
https://your-domain.com/a/[publicKey]
```

The public key is an 8-character identifier unique to your agent (e.g., `/a/6bbfebeb`).

<Tip>
  Click the copy button to copy the URL to your clipboard, or click "Open Kiosk in New Tab" to preview it in your browser.
</Tip>

***

## Setting Up the Device

### Basic Setup

<Steps>
  <Step title="Open the URL">
    Navigate to the kiosk URL in the device's web browser.
  </Step>

  <Step title="Enter full-screen mode">
    Use the browser's full-screen mode (usually F11 on desktop, or the kiosk/guided access mode on tablets).
  </Step>

  <Step title="Test the flow">
    Tap through the visitor flow to verify language selection, contact search, and calling work correctly.
  </Step>

  <Step title="Lock the device">
    Use your device's kiosk mode or guided access to prevent visitors from navigating away.
  </Step>
</Steps>

### iPad / iOS

1. Open Safari and navigate to the kiosk URL
2. Go to **Settings → Accessibility → Guided Access**
3. Enable Guided Access
4. Return to Safari and triple-click the side button to start Guided Access
5. This locks the device to the kiosk screen

### Android Tablets

1. Open Chrome and navigate to the kiosk URL
2. Use your device's **Kiosk Mode** or a kiosk lockdown app (e.g., SureLock, KioWare)
3. Alternatively, use **Screen Pinning** from Settings → Security

### Desktop / Wall Display

1. Open Chrome or any modern browser
2. Navigate to the kiosk URL
3. Press **F11** for full-screen mode
4. Consider using Chrome's `--kiosk` flag for a locked-down experience:

```bash theme={null}
chrome --kiosk https://your-domain.com/a/[publicKey]
```

***

## Orientation

The kiosk automatically adapts to the screen orientation:

| Orientation   | Layout                                       | Best For                             |
| ------------- | -------------------------------------------- | ------------------------------------ |
| **Portrait**  | Vertical layout with stacked elements        | Tablet stands, wall-mounted displays |
| **Landscape** | Horizontal layout with side-by-side elements | Desk screens, reception counters     |

<Note>
  Orientation is determined by the device screen, not a saved setting. The same URL works on any orientation. You can preview both orientations in the Playground.
</Note>

***

## Testing

Before going live, verify:

| Check                  | How to Test                                                             |
| ---------------------- | ----------------------------------------------------------------------- |
| **Attract screen**     | Leave the kiosk idle — it should show your branding and avatar          |
| **Language selection** | Tap to start and verify available languages                             |
| **Contact search**     | Search for a contact by name, phone, or email                           |
| **Calling flow**       | Select a contact and verify the call/notification flow                  |
| **Return to idle**     | After the goodbye screen, the kiosk should return to the attract screen |
| **Theme and colors**   | Verify your brand colors, logo, and theme look correct                  |

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Kiosk shows a blank page" icon="circle-exclamation">
    **Possible causes:**

    * Invalid or expired public key
    * Network connectivity issues
    * Browser blocking JavaScript

    **Solutions:**

    * Verify the URL matches what's shown in the Playground
    * Check the device has internet access
    * Try a different browser
  </Accordion>

  <Accordion title="Contact search returns no results" icon="magnifying-glass">
    **Possible causes:**

    * No contacts have been added
    * Search term doesn't match any contacts

    **Solutions:**

    * Add contacts from the Contacts page in the dashboard
    * Verify contacts have been saved successfully
  </Accordion>

  <Accordion title="Kiosk doesn't return to attract screen" icon="rotate-left">
    **Possible causes:**

    * The visitor flow may be waiting for input
    * Browser may have cached a state

    **Solutions:**

    * Refresh the page to reset to the attract screen
    * The kiosk auto-returns after the goodbye screen with a timeout
  </Accordion>

  <Accordion title="Wrong orientation" icon="mobile">
    **Possible causes:**

    * Device orientation lock is enabled

    **Solutions:**

    * Disable orientation lock on the device
    * Rotate the device to the desired orientation
    * The kiosk adapts automatically
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Manage Contacts" icon="address-book" href="/receptionist/contacts">
    Add or update the employee directory for your kiosk.
  </Card>

  <Card title="Customize Styling" icon="palette" href="/receptionist/styling">
    Adjust the kiosk theme, colors, and avatar.
  </Card>

  <Card title="View Analytics" icon="chart-line" href="/receptionist/analytics">
    Monitor kiosk usage and visitor interactions.
  </Card>

  <Card title="Agent Overview" icon="robot" href="/agents/overview">
    Learn about Cosmo channels and core concepts.
  </Card>
</CardGroup>


# Kiosk Avatar Onboarding
Source: https://docs.cosmo.humanizing.com/receptionist/onboarding

Step-by-step guide to creating a Kiosk Avatar through the onboarding wizard

## Overview

The Kiosk Avatar onboarding wizard guides you through creating a kiosk-ready front desk experience in four steps. The process extracts your brand identity, lets you import contacts, and configures the kiosk appearance.

<Tip>
  The wizard is designed to get you up and running quickly. You can always refine contacts, styling, and settings after the initial setup.
</Tip>

## Starting the Wizard

1. Navigate to **Agents → Create New Agent**
2. Select **Kiosk Avatar** as the channel
3. The onboarding wizard opens with a 4-step flow

## The 4-Step Process

<Steps>
  <Step title="Name & Domain">
    Name your Kiosk Avatar and enter your company domain for brand extraction.
  </Step>

  <Step title="Import Contacts">
    Add employee contacts that visitors can search and call from the kiosk.
  </Step>

  <Step title="Customize Appearance">
    Select an avatar, theme, and brand colors for the kiosk.
  </Step>

  <Step title="Review & Create">
    Review your configuration and create the agent.
  </Step>
</Steps>

***

## Step 1: Name & Domain

### Agent Name

Give your Kiosk Avatar a descriptive name. This appears in the dashboard to identify it among your agents.

<Note>
  If you leave the name blank, it defaults to "Kiosk Avatar" with the current date and time.
</Note>

### Company Domain

Enter your company website URL (e.g., `https://humanizing.com`). The platform uses this to:

* **Extract brand colors** via Brandfetch integration
* **Detect your logo** for kiosk branding
* **Set context** for the Kiosk Avatar's identity

You can click **Example** to pre-fill with `humanizing.com` and see how extraction works.

### Brand Extraction

After entering a domain, click **Extract** to fetch brand colors and logo. The extracted colors appear as swatches you can select as your primary brand color.

<Tip>
  If extraction doesn't find your exact colors, you can manually enter a hex code or use the color picker. Click "Skip" to proceed without brand extraction.
</Tip>

***

## Step 2: Import Contacts

Add the employees that visitors will be able to find and contact through the kiosk.

### Adding Contacts

There are three ways to add contacts:

| Method                   | Description                                        |
| ------------------------ | -------------------------------------------------- |
| **Manual entry**         | Fill in name, phone, and email for each contact    |
| **CSV import**           | Upload a CSV file with columns: name, phone, email |
| **Paste from clipboard** | Paste comma-separated contact data directly        |

### Example Contacts

Click **Add 3 Example Contacts** to populate the list with sample data. This helps you see how the contact list will look and test the kiosk flow.

### Contact Fields

Each contact has three fields:

| Field     | Required | Description                           |
| --------- | -------- | ------------------------------------- |
| **Name**  | Yes      | Full name displayed in search results |
| **Phone** | No       | Phone number for calling              |
| **Email** | No       | Email address for search              |

<Note>
  This step is optional. Click **Skip for now** to proceed without contacts and add them later from the Contacts page.
</Note>

***

## Step 3: Customize Appearance

Configure how the kiosk looks to visitors.

### Avatar Selection

Choose a 3D avatar from the gallery. The avatar appears on the kiosk attract screen and throughout the visitor flow.

### Theme

Select between **Light** and **Dark** mode for the kiosk interface.

| Theme     | Best For                                             |
| --------- | ---------------------------------------------------- |
| **Light** | Bright lobbies, corporate offices, reception desks   |
| **Dark**  | Dimmer environments, modern aesthetics, tech offices |

### Brand Colors

Select or customize your primary brand color. You can:

* Click an extracted color swatch from Step 1
* Use the color picker
* Enter a hex code manually

### Preview

The right side of the screen shows a live preview of the kiosk with your current settings. Toggle between **Portrait** and **Landscape** orientations to see how it looks on different devices.

***

## Step 4: Review & Create

Review all your settings before creating the agent:

* **Agent name** and domain
* **Contacts** count
* **Avatar**, theme, and brand color

Click **Create Kiosk Avatar** to finalize. The agent is created and you're redirected to the Playground where you can:

* Preview the kiosk
* Copy the deployment URL
* Test the visitor flow

***

## After Onboarding

<CardGroup>
  <Card title="Preview in Playground" icon="flask" href="/receptionist/deployment">
    Test the full kiosk flow and copy the deployment URL.
  </Card>

  <Card title="Manage Contacts" icon="address-book" href="/receptionist/contacts">
    Add, edit, or import more contacts for the kiosk directory.
  </Card>

  <Card title="Customize Styling" icon="palette" href="/receptionist/styling">
    Adjust avatar, theme, colors, and logo from the Styling page.
  </Card>

  <Card title="Deploy to Device" icon="rocket" href="/receptionist/deployment">
    Open the kiosk URL on a tablet or touchscreen to go live.
  </Card>
</CardGroup>


# Kiosk Avatar Overview
Source: https://docs.cosmo.humanizing.com/receptionist/overview

Learn about the Kiosk Avatar channel for kiosk-based visitor management at offices, hotels, and corporate lobbies

## What is a Kiosk Avatar?

The Kiosk Avatar is Cosmo's front desk channel for physical locations. It runs on a tablet or touchscreen display as a kiosk, guiding visitors through a multi-screen flow to check in, find contacts, and connect with the right person.

<Tip>
  Unlike the Chatbot, the Kiosk Avatar is a full-screen kiosk experience optimized for touch interaction and visitor self-service.
</Tip>

## Key Features

<CardGroup>
  <Card title="Multi-Screen Kiosk Flow" icon="display">
    Guided visitor journey through attract screen, language selection, visit type, contact search, calling, and confirmation.
  </Card>

  <Card title="Contact Directory" icon="address-book">
    Import and manage employee contacts. Visitors search by name, phone, or email and connect directly.
  </Card>

  <Card title="45+ Languages" icon="globe">
    Welcome visitors in their native language with a language selection screen at the start of the flow.
  </Card>

  <Card title="Brand Customization" icon="palette">
    Custom themes, brand colors, logos, and 3D avatars. Automatic brand extraction from your domain.
  </Card>
</CardGroup>

## Kiosk Flow

The Kiosk Avatar guides visitors through a series of screens:

<Steps>
  <Step title="Attract Screen">
    An idle screen displayed when no one is interacting. Shows your branding, avatar, and a prompt to start.
  </Step>

  <Step title="Language Selection">
    Visitors choose their preferred language. The entire flow adapts to the selected language.
  </Step>

  <Step title="Visit Type">
    Visitors select why they're here (appointment, delivery, interview, etc.).
  </Step>

  <Step title="Contact Search">
    Search the employee directory by name, phone, or email to find the right person.
  </Step>

  <Step title="Calling">
    The kiosk initiates a call or notification to the selected contact.
  </Step>

  <Step title="Confirmation & Goodbye">
    A confirmation screen followed by a goodbye message before returning to the attract screen.
  </Step>
</Steps>

## Kiosk Avatar vs Chatbot

| Feature            | Chatbot                 | Kiosk Avatar                 |
| ------------------ | ----------------------- | ---------------------------- |
| **Interface**      | Chat widget (bubble)    | Full-screen kiosk            |
| **Deployment**     | Embed script on website | Public URL on tablet/display |
| **Input**          | Text chat               | Touch navigation             |
| **Knowledge Base** | Web pages, text, Q\&A   | Contact directory            |
| **Orientation**    | Responsive              | Portrait or landscape        |
| **Use Case**       | Online customer support | In-person visitor management |

## Deployment

The Kiosk Avatar deploys as a simple public URL:

```
https://your-domain.com/a/[publicKey]
```

Open this URL on any tablet or touchscreen in full-screen/kiosk mode. The kiosk adapts to the screen orientation automatically.

<Note>
  The public key is an 8-character identifier generated when you create the agent. Find it in the Playground page under "Deploy Kiosk."
</Note>

### Hardware Recommendations

| Setup                 | Recommended Hardware                 |
| --------------------- | ------------------------------------ |
| **Desk-mounted**      | iPad or Android tablet in a stand    |
| **Wall-mounted**      | Large touchscreen display (portrait) |
| **Reception counter** | Tablet in landscape orientation      |

## Credit Consumption

Kiosk Avatar voice calls consume credits from your workspace balance at a rate of **50 credits per started minute**.

| Event                               | Credits Consumed |
| ----------------------------------- | ---------------- |
| Call starts (first minute)          | 50 credits       |
| Each additional started minute      | 50 credits       |
| Call blocked (insufficient balance) | 0 credits        |

<Note>
  If your credit balance drops to zero during a call, the call ends gracefully. Calls will not start if fewer than 50 credits are available.
</Note>

## Getting Started

<CardGroup>
  <Card title="Create a Kiosk Avatar" icon="wand-magic-sparkles" href="/receptionist/onboarding">
    Follow the onboarding wizard to set up your first Kiosk Avatar.
  </Card>

  <Card title="Manage Contacts" icon="address-book" href="/receptionist/contacts">
    Import and manage the employee directory for your kiosk.
  </Card>

  <Card title="Customize Kiosk" icon="palette" href="/receptionist/styling">
    Configure themes, colors, avatars, and branding for your kiosk.
  </Card>

  <Card title="Deploy Kiosk" icon="rocket" href="/receptionist/deployment">
    Get your kiosk URL and deploy to a physical device.
  </Card>
</CardGroup>


# Kiosk Styling
Source: https://docs.cosmo.humanizing.com/receptionist/styling

Customize your Kiosk Avatar with avatars, themes, and brand colors

## Overview

The Styling page lets you customize how the Kiosk Avatar looks to visitors. All changes apply to the live kiosk in real-time after saving.

## Accessing Styling

Navigate to your Kiosk Avatar in the sidebar, then click **Styling**.

***

## Avatar

Choose a 3D avatar that represents your receptionist. The avatar appears on the attract screen and throughout the kiosk flow.

* Browse the avatar gallery to select from pre-made avatars
* The preview updates in real-time as you browse
* Click an avatar to select it, then save

<Tip>
  Choose an avatar that matches your company culture. A professional avatar works well for corporate offices, while a friendlier one suits hospitality venues.
</Tip>

***

## Theme

Select the kiosk color scheme:

| Theme     | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| **Light** | White background with dark text. Best for bright environments.     |
| **Dark**  | Dark background with light text. Best for modern or dimmer spaces. |

***

## Brand Color

Set the primary accent color used throughout the kiosk (buttons, highlights, headers):

* **Extracted colors**: If you provided a domain during onboarding, extracted brand colors appear as swatches
* **Color picker**: Click to choose any color visually
* **Hex code**: Enter an exact color value (e.g., `#3B82F6`)

***

## Logo

Upload or change your company logo displayed on the kiosk header. The logo appears alongside your brand name on every screen.

<Note>
  If you used brand extraction during onboarding, your logo was automatically imported. You can replace or remove it here.
</Note>

***

## Preview

The right side of the Styling page shows a live kiosk preview. Use the orientation toggle in the header to switch between:

* **Portrait** — Vertical layout for tablet stands
* **Landscape** — Horizontal layout for desk-mounted screens

The preview reflects all unsaved changes so you can see the result before saving.

***

## Saving Changes

Click **Save** to apply your styling changes. The kiosk updates in real-time — any device displaying the kiosk URL will reflect the new styles on the next screen transition.

<Warning>
  Changes are not saved automatically. If you navigate away without saving, a confirmation dialog will prompt you to save or discard changes.
</Warning>

***

## Next Steps

<CardGroup>
  <Card title="Manage Contacts" icon="address-book" href="/receptionist/contacts">
    Add or update employee contacts for the kiosk directory.
  </Card>

  <Card title="Deploy Your Kiosk" icon="rocket" href="/receptionist/deployment">
    Get the deployment URL and set up your physical device.
  </Card>
</CardGroup>


# Knowledge Sources Overview
Source: https://docs.cosmo.humanizing.com/sources/overview

Learn how to build your agent's knowledge base with web pages, custom text, and Q&A content

## What is a Knowledge Base?

A **knowledge base** is the foundation of your agent's intelligence. It's a collection of information sources that your agent draws from when answering visitor questions. The quality and relevance of your knowledge base directly determines how helpful your agent will be.

<Tip>
  Think of the knowledge base as your agent's memory. The more relevant, well-organized content you provide, the better your agent can assist visitors with accurate, contextual answers.
</Tip>

## How It Works

When a visitor asks your agent a question, here's what happens behind the scenes:

<Steps>
  <Step title="Query Processing">
    The visitor's question is analyzed and converted into a format that can be searched against your knowledge base.
  </Step>

  <Step title="Content Retrieval">
    The system searches through all your knowledge sources to find the most relevant content pieces that match the query.
  </Step>

  <Step title="Reranking">
    Retrieved content is reranked by relevance to ensure the best information is prioritized.
  </Step>

  <Step title="Response Generation">
    The AI generates a natural, conversational response using the retrieved content as context, ensuring accuracy based on your actual content.
  </Step>
</Steps>

This approach is called **Retrieval-Augmented Generation (RAG)** and ensures your agent provides accurate answers grounded in your content rather than making things up.

## Source Types

Your knowledge base can include three types of content sources:

| Source Type      | Description                                                 | Best Use Cases                                                       |
| ---------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
| **Web Sources**  | Pages imported from your website via URL, sitemap, or crawl | Product pages, documentation, blog posts, service descriptions       |
| **Text Sources** | Custom content you write directly in the platform           | Internal knowledge, company policies, specialized information        |
| **Q\&A Sources** | Specific question-answer pairs you define                   | FAQs, common support queries, precise answers for specific questions |

<CardGroup>
  <Card title="Web Sources" icon="globe" href="/sources/web-sources">
    Import content directly from your website pages, sitemaps, or through automated crawling.
  </Card>

  <Card title="Text Sources" icon="file-lines" href="/sources/text-sources">
    Add custom text content that may not exist on your website.
  </Card>

  <Card title="Q&A Sources" icon="circle-question" href="/sources/qa-sources">
    Create targeted question-answer pairs for precise responses.
  </Card>
</CardGroup>

## Managing Sources

All your knowledge sources are managed from the **Sources** tab in your agent's dashboard. From there you can:

* **Add** new sources of any type
* **View** all existing sources and their status — source URLs are clickable and open in a new tab for quick verification
* **Select All** sources at once using the checkbox in the table header to perform bulk operations
* **Edit** source content (for text and Q\&A)
* **Delete** sources you no longer need
* **Monitor** ingestion status and processing

<Note>
  When you add or update sources, your agent's knowledge base is automatically updated. Changes typically take effect within a few minutes after processing completes.
</Note>

## Source Status

Each source has a status indicating its current state:

| Status         | Meaning                                                |
| -------------- | ------------------------------------------------------ |
| **Pending**    | Source is queued for processing                        |
| **Processing** | Content is being extracted and indexed                 |
| **Ready**      | Source is active and available to your agent           |
| **Failed**     | Processing encountered an error (check source details) |

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Focus on quality over quantity">
    Adding hundreds of irrelevant pages can actually hurt your agent's performance. Be selective and include only content that visitors would actually ask about.
  </Accordion>

  <Accordion icon="sitemap" title="Organize content logically">
    Group related information together. If you have product pages, support articles, and company info, make sure each is well-structured and covers topics comprehensively.
  </Accordion>

  <Accordion icon="arrows-rotate" title="Keep content up to date">
    Remove outdated sources and add new content regularly. An agent giving outdated information can frustrate visitors and damage trust.
  </Accordion>

  <Accordion icon="layer-group" title="Use multiple source types together">
    Web sources are great for existing content, but supplement with Q\&A pairs for common questions and text sources for information not on your website.
  </Accordion>

  <Accordion icon="flask" title="Test after adding sources">
    After adding new sources, test your agent in the Playground with relevant questions to verify it's using the new content appropriately.
  </Accordion>
</AccordionGroup>

## Common Scenarios

### Scenario 1: Documentation Website

If you have technical documentation, import your docs pages via sitemap. Supplement with Q\&A pairs for the most common "how do I..." questions.

### Scenario 2: E-commerce Site

Import product pages and category descriptions. Add Q\&A pairs for shipping policies, return processes, and sizing guides that might not be in your main content.

### Scenario 3: Service Business

Import your services pages and case studies. Add text sources for internal processes and Q\&A pairs for pricing and availability questions.

## Next Steps

<CardGroup>
  <Card title="Add Web Sources" icon="globe" href="/sources/web-sources">
    Learn how to import content from your website using URLs, sitemaps, or crawling.
  </Card>

  <Card title="Create Text Sources" icon="file-lines" href="/sources/text-sources">
    Add custom text content to your knowledge base.
  </Card>

  <Card title="Build Q&A Pairs" icon="circle-question" href="/sources/qa-sources">
    Create targeted question-answer pairs for precise responses.
  </Card>

  <Card title="Test Your Agent" icon="flask" href="/agents/playground">
    Verify your knowledge base is working in the Playground.
  </Card>
</CardGroup>


# Q&A Sources
Source: https://docs.cosmo.humanizing.com/sources/qa-sources

Create targeted question-answer pairs for precise, consistent responses to frequently asked questions

## Overview

Q\&A sources allow you to define specific question-answer pairs that your agent can use when visitors ask common questions. Unlike web and text sources where the AI interprets content, Q\&A pairs give you direct control over exactly how your agent responds to specific queries.

<Tip>
  Q\&A sources are perfect for frequently asked questions where you want guaranteed, consistent answers. When a visitor asks something matching a Q\&A pair, the agent will use your exact answer rather than generating one.
</Tip>

## When to Use Q\&A Sources

Q\&A sources excel in situations where precision matters:

| Use Case                         | Example                                                      |
| -------------------------------- | ------------------------------------------------------------ |
| **Common support questions**     | "What are your business hours?" → Exact hours with timezone  |
| **Policy clarifications**        | "What's your refund policy?" → Word-perfect policy statement |
| **Pricing inquiries**            | "How much does shipping cost?" → Current shipping rates      |
| **Technical specifications**     | "What's the battery life?" → Precise specification           |
| **Compliance-sensitive answers** | Legal disclaimers, terms of service summaries                |
| **Brand messaging**              | Company positioning, unique value propositions               |

<Note>
  Q\&A sources work alongside web and text sources. Use Q\&A for questions requiring exact answers, and other sources for broader topics where the AI can synthesize information.
</Note>

***

## Adding a Q\&A Entry

To add a new question-answer pair to your agent's knowledge base:

<Steps>
  <Step title="Navigate to Q&A Sources">
    Go to your agent's **Sources** tab and select **Q\&A** from the source type options.
  </Step>

  <Step title="Click Add New">
    Switch to the **Add New** tab to access the Q\&A entry form.
  </Step>

  <Step title="Enter the Question">
    Type a question that visitors commonly ask. Write it naturally, as a real person would phrase it.

    **Effective questions:**

    * "What are your shipping options?"
    * "How do I reset my password?"
    * "Do you offer student discounts?"

    <Tip>
      Think about the different ways visitors might phrase the same question. The AI can match similar variations, but using natural language helps.
    </Tip>
  </Step>

  <Step title="Enter the Answer">
    Provide the complete answer you want your agent to use. Be thorough but concise - include all necessary information without unnecessary padding.
  </Step>

  <Step title="Save">
    Click **Add Q\&A** to save your entry. It will be added to your knowledge base and become available to your agent.
  </Step>
</Steps>

***

## How Q\&A Matching Works

When a visitor asks a question, the system doesn't just look for exact matches - it uses semantic understanding to find relevant Q\&A pairs:

<AccordionGroup>
  <Accordion icon="brain" title="Semantic matching">
    The AI understands meaning, not just keywords. If you have a Q\&A for "What are your business hours?" it will also match:

    * "When are you open?"
    * "What time do you close?"
    * "Are you open on weekends?"
    * "Opening hours?"
  </Accordion>

  <Accordion icon="ranking-star" title="Relevance ranking">
    When multiple Q\&A pairs might be relevant, the system ranks them by relevance to choose the best match. If the visitor's question closely matches a Q\&A, that answer is prioritized.
  </Accordion>

  <Accordion icon="layer-group" title="Combined with other sources">
    Q\&A answers can be combined with information from your web and text sources when the AI needs additional context to fully answer a visitor's question.
  </Accordion>
</AccordionGroup>

***

## Managing Q\&A Entries

### Viewing Your Q\&A Pairs

All your Q\&A entries appear in the **My Sources** tab when Q\&A is selected:

* **Question** - The question you defined
* **Answer** - Preview of your answer content
* **Status** - Processing status (Pending, Processing, Ready, Failed)
* **Created date** - When the entry was added
* **Actions** - Edit and delete options

### Editing a Q\&A Entry

To update an existing Q\&A pair:

1. Find the entry in **My Sources**
2. Click the **Edit** button (pencil icon)
3. Modify the question or answer as needed
4. Click **Save Changes**

<Note>
  After editing a Q\&A entry, you'll need to click **Train Agent** to reprocess the content and update your agent's knowledge base with the changes.
</Note>

### Deleting a Q\&A Entry

To remove a Q\&A pair:

1. Find the entry in **My Sources**
2. Click the **Delete** button (trash icon)
3. Confirm the deletion

<Warning>
  Deleting a Q\&A entry means your agent will no longer have this targeted answer available. It may still answer similar questions using other sources, but without the precision of your Q\&A pair.
</Warning>

### Bulk Management

For agents with many Q\&A entries:

* Use the search filter to find specific entries
* Select multiple entries for bulk deletion
* Sort by date to find recently added entries

***

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Be specific but comprehensive">
    Your answer should fully address the question without requiring follow-up. Include all relevant details.

    **Good example:**
    Q: "What's your return policy?"
    A: "We accept returns within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed to your original payment method within 5-7 business days after we receive your return. Return shipping is free for defective items; otherwise, a \$5.99 return label fee applies."

    **Poor example:**
    Q: "What's your return policy?"
    A: "30 days."
  </Accordion>

  <Accordion icon="message-question" title="Use natural question phrasing">
    Write questions the way real visitors would ask them. Avoid overly formal or technical language unless your audience uses it.

    **Better:** "How do I track my order?"
    **Avoid:** "What is the order tracking procedure?"
  </Accordion>

  <Accordion icon="copy" title="Don't duplicate web content">
    If information is already well-covered on your website (and imported as a web source), you don't need a Q\&A for it. Reserve Q\&A pairs for:

    * Questions that need exact wording
    * Information not on your website
    * Clarifications of complex topics
  </Accordion>

  <Accordion icon="arrows-rotate" title="Keep answers current">
    Review Q\&A entries regularly, especially for:

    * Pricing (update when prices change)
    * Hours (update for holidays/seasonal changes)
    * Policies (update when terms change)
    * Contact info (update when details change)
  </Accordion>

  <Accordion icon="layer-group" title="Group related FAQs">
    Consider organizing your Q\&A entries by topic in your internal documentation so you can keep track of what you've covered:

    * Shipping & Delivery
    * Returns & Refunds
    * Account & Billing
    * Product Information
  </Accordion>

  <Accordion icon="flask" title="Test thoroughly">
    After adding Q\&A entries, test your agent with various phrasings of each question to ensure it correctly uses your answers.
  </Accordion>
</AccordionGroup>

***

## Q\&A Examples by Category

### Shipping & Delivery

```
Q: How long does shipping take?
A: Standard shipping takes 5-7 business days within the continental US.
   Express shipping (2-3 business days) is available for $12.99.
   Overnight shipping is available for $24.99 (order by 2 PM EST).
   Alaska, Hawaii, and international orders may take longer.
```

```
Q: Do you ship internationally?
A: Yes, we ship to over 50 countries! International shipping costs are
   calculated at checkout based on destination and package weight.
   Delivery typically takes 10-21 business days. Note that customers
   are responsible for any customs duties or import taxes.
```

### Returns & Refunds

```
Q: Can I return an item?
A: Yes! We offer hassle-free returns within 30 days of delivery.
   Items must be unused and in original packaging. Start your return
   from your Account > Order History page. Once we receive and inspect
   your return, your refund will be processed within 5-7 business days.
```

```
Q: How do I get a refund?
A: Refunds are processed automatically once we receive and verify your
   returned item. The refund goes to your original payment method and
   typically appears within 5-7 business days, though your bank may
   take additional time to post the credit.
```

### Account & Billing

```
Q: How do I reset my password?
A: Click "Forgot Password" on the login page and enter your email
   address. We'll send you a reset link valid for 24 hours. If you
   don't see the email, check your spam folder or contact support
   at support@example.com.
```

```
Q: What payment methods do you accept?
A: We accept Visa, Mastercard, American Express, Discover, PayPal,
   Apple Pay, and Google Pay. All transactions are secured with
   256-bit SSL encryption.
```

### Product Information

```
Q: Is this product in stock?
A: Stock availability is shown on each product page. If an item is
   out of stock, you can click "Notify Me" to receive an email when
   it's back. Popular items often restock within 1-2 weeks.
```

```
Q: Do you offer a warranty?
A: Yes! All products come with a 1-year limited warranty covering
   manufacturing defects. Extended warranties (2 or 3 years) are
   available for purchase at checkout. Keep your receipt for
   warranty claims.
```

### Business Information

```
Q: What are your customer service hours?
A: Our support team is available:
   - Monday to Friday: 9 AM - 8 PM EST
   - Saturday: 10 AM - 6 PM EST
   - Sunday: Closed
   You can also email us anytime at support@example.com and we'll
   respond within 24 hours.
```

```
Q: Where are you located?
A: Our headquarters is in Austin, Texas. We don't have a physical
   retail store - we're an online-only company. This helps us keep
   prices low and ship directly to you!
```

***

## Common Issues

### Q\&A Not Being Used

If your agent isn't using your Q\&A answers:

1. **Check the status** - Ensure the Q\&A shows as "Ready" in My Sources
2. **Train your agent** - Click "Train Agent" after adding new entries
3. **Test exact phrasing** - First test with your exact question to verify it works
4. **Check for conflicts** - Multiple Q\&As on similar topics may compete

### Answer Seems Incomplete

If the agent provides a partial answer:

* Review your Q\&A answer - is it complete?
* Check if other sources have conflicting information
* Consider whether the visitor's question is broader than your Q\&A covers

### Too Many Similar Q\&As

If you have multiple Q\&A pairs that overlap:

* Consolidate similar questions into one comprehensive Q\&A
* Keep the most complete answer and delete redundant entries
* Use text sources for broader topics that require multiple Q\&A pairs

***

## Q\&A vs. Text Sources

Not sure whether to use Q\&A or text sources? Here's a guide:

| Factor               | Use Q\&A                             | Use Text                             |
| -------------------- | ------------------------------------ | ------------------------------------ |
| **Content format**   | Single question with specific answer | Multiple topics or longer content    |
| **Answer precision** | Exact wording matters                | AI interpretation is fine            |
| **Content length**   | Short to medium answers              | Long-form content                    |
| **Update frequency** | Changes often (prices, hours)        | Relatively stable content            |
| **Organization**     | Standalone questions                 | Related information grouped together |

<Tip>
  When in doubt, try both! Add a Q\&A pair for the most common phrasing of a question, and include the same information in a text source for broader coverage.
</Tip>

***

## Next Steps

<CardGroup>
  <Card title="Web Sources" icon="globe" href="/sources/web-sources">
    Import content from your website pages.
  </Card>

  <Card title="Text Sources" icon="file-lines" href="/sources/text-sources">
    Add custom text content to your knowledge base.
  </Card>

  <Card title="Test Your Agent" icon="flask" href="/agents/playground">
    Verify your Q\&A pairs work in the Playground.
  </Card>

  <Card title="Sources Overview" icon="database" href="/sources/overview">
    Learn about all source types and best practices.
  </Card>
</CardGroup>


# Text Sources
Source: https://docs.cosmo.humanizing.com/sources/text-sources

Add custom text content to your agent's knowledge base for information not available on your website

## Overview

Text sources allow you to add custom content directly to your agent's knowledge base. This is perfect for information that doesn't exist on your website, such as internal policies, specialized knowledge, or supplementary content that helps your agent answer questions more comprehensively.

<Tip>
  Text sources are ideal for company-specific information like internal processes, detailed product specifications, or answers to questions that visitors frequently ask but aren't covered on your website.
</Tip>

## When to Use Text Sources

Text sources fill the gaps that web sources can't cover:

| Use Case                    | Example                                                     |
| --------------------------- | ----------------------------------------------------------- |
| **Internal policies**       | Return policies, shipping procedures, warranty terms        |
| **Company information**     | Company history, mission statements, team bios              |
| **Detailed specifications** | Technical specs, compatibility information, sizing guides   |
| **Process documentation**   | How-to guides, step-by-step instructions                    |
| **Supplementary content**   | Information that complements your website content           |
| **Temporary content**       | Seasonal promotions, event information, limited-time offers |

<Note>
  Unlike web sources that are imported from URLs, text sources are created and maintained entirely within the platform. This gives you complete control over the content without needing to update your website.
</Note>

***

## Adding a Text Source

To add a new text source to your agent's knowledge base:

<Steps>
  <Step title="Navigate to Text Sources">
    Go to your agent's **Sources** tab and select **Text** from the source type options.
  </Step>

  <Step title="Click Add New">
    Switch to the **Add New** tab to access the text entry form.
  </Step>

  <Step title="Enter a Title">
    Provide a descriptive title for your text source. This helps you identify the content later and improves organization.

    **Good titles:**

    * "Return Policy Details"
    * "Product Compatibility Guide"
    * "Company History and Mission"

    **Avoid generic titles like:**

    * "Info"
    * "Text 1"
    * "Content"
  </Step>

  <Step title="Add Your Content">
    Enter the content you want your agent to learn from. The rich text editor supports formatting to help structure your content clearly.
  </Step>

  <Step title="Save">
    Click **Add Text** to save your content. It will be added to your knowledge base and become available to your agent.
  </Step>
</Steps>

***

## Rich Text Editor

The text source editor includes rich text formatting capabilities to help you structure content effectively:

### Supported Formatting

| Format       | Purpose                                                   |
| ------------ | --------------------------------------------------------- |
| **Bold**     | Emphasize important terms and key points                  |
| *Italic*     | Add emphasis or denote special terms                      |
| **Headings** | Create sections and organize content hierarchy            |
| **Lists**    | Bullet points and numbered lists for step-by-step content |
| **Links**    | Include clickable URLs to external resources              |

### Formatting Tips

<AccordionGroup>
  <Accordion icon="heading" title="Use headings for structure">
    Break long content into sections with clear headings. This helps both users reading the content and the AI when retrieving relevant information.

    ```
    ## Shipping Information

    ### Domestic Shipping
    We offer free shipping on orders over $50...

    ### International Shipping
    International orders are shipped via...
    ```
  </Accordion>

  <Accordion icon="list" title="Use lists for processes">
    When documenting step-by-step processes, use numbered lists:

    ```
    To return an item:
    1. Log into your account
    2. Navigate to Order History
    3. Select the item to return
    4. Print the return label
    ```
  </Accordion>

  <Accordion icon="bold" title="Highlight key information">
    Use bold text to emphasize critical details that your agent should prioritize in responses:

    "Returns must be initiated within **30 days** of purchase."
  </Accordion>
</AccordionGroup>

***

## Managing Text Sources

### Viewing Your Sources

All your text sources appear in the **My Sources** tab with:

* **Title** - The name you gave the source
* **Status** - Current processing status (Pending, Processing, Ready, Failed)
* **Created date** - When the source was added
* **Actions** - Edit and delete options

### Editing a Text Source

To update an existing text source:

1. Find the source in **My Sources**
2. Click the **Edit** button (pencil icon)
3. Modify the title or content as needed
4. Click **Save Changes**

<Note>
  The text editor has a maximum display height of approximately 500px. When your content exceeds this, the editor becomes scrollable — your full content is preserved and processed correctly. The **Save Changes** button is always visible at the bottom of the modal regardless of content length.
</Note>

<Note>
  After editing a text source, you'll need to click **Train Agent** to reprocess the content and update your agent's knowledge base with the changes.
</Note>

### Deleting a Text Source

To remove a text source:

1. Find the source in **My Sources**
2. Click the **Delete** button (trash icon)
3. Confirm the deletion

<Warning>
  Deleting a text source permanently removes it from your knowledge base. The agent will no longer have access to this information when answering questions.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Be specific and comprehensive">
    Include all relevant details in your text sources. The more complete the information, the better your agent can answer questions.

    **Good example:**
    "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed within 5-7 business days after we receive the returned item. Shipping costs are non-refundable unless the return is due to our error."

    **Poor example:**
    "We accept returns."
  </Accordion>

  <Accordion icon="sitemap" title="Organize content logically">
    Group related information together in single text sources rather than creating many small, fragmented entries.

    **Better approach:**
    Create one comprehensive "Shipping & Returns" text source covering all related policies.

    **Avoid:**
    Separate sources for "Returns", "Shipping times", "Return shipping", "Refund processing" when they're all related.
  </Accordion>

  <Accordion icon="pen" title="Write in natural language">
    Write content as if you were explaining it to a customer. The AI works best with clear, conversational content.

    **Good:**
    "If your order arrives damaged, please contact us within 48 hours with photos of the damage. We'll arrange a replacement or refund at no additional cost to you."

    **Less effective:**
    "Damaged items: contact support, 48hr limit, photos required, replacement/refund available."
  </Accordion>

  <Accordion icon="arrows-rotate" title="Keep content current">
    Review and update text sources regularly, especially for time-sensitive information like policies, pricing, or promotions.
  </Accordion>

  <Accordion icon="flask" title="Test after adding">
    After adding text sources, test your agent in the Playground with relevant questions to verify the content is being used effectively.
  </Accordion>
</AccordionGroup>

***

## Content Examples

### Example 1: Company Information

```
## About Our Company

Founded in 2015, Acme Corp has been providing innovative solutions
for small businesses. Our mission is to simplify operations and
help businesses grow.

### Our Team
We have a team of 50+ dedicated professionals across engineering,
customer support, and sales.

### Contact Information
- Email: support@acmecorp.com
- Phone: 1-800-ACME-123
- Hours: Monday-Friday, 9 AM - 6 PM EST
```

### Example 2: Product Specifications

```
## Widget Pro Technical Specifications

**Dimensions:** 6" x 4" x 2"
**Weight:** 1.5 lbs
**Power:** USB-C, 5V/2A
**Battery:** 5000mAh lithium-ion
**Charging time:** 2 hours
**Operating temperature:** 32°F - 104°F

### Compatibility
- Works with Windows 10/11, macOS 10.15+
- iOS 14+ and Android 10+ for mobile app
- Requires Bluetooth 5.0 for wireless features
```

### Example 3: FAQ Content

```
## Frequently Asked Questions

### Do you offer gift wrapping?
Yes! We offer gift wrapping for $5 per item. Select the gift wrap
option at checkout and include a personalized message.

### Can I change my order after placing it?
Orders can be modified within 1 hour of placement. Contact our
support team immediately if you need to make changes.

### Do you price match?
We match prices from authorized retailers. Submit a price match
request within 14 days of purchase with proof of the lower price.
```

***

## Common Issues

### Content Not Appearing in Responses

If your agent isn't using the text source content:

1. **Check the status** - Ensure the source shows as "Ready" in My Sources
2. **Train your agent** - Click "Train Agent" after adding new content
3. **Test with specific questions** - Ask questions directly related to the content
4. **Check for conflicts** - Other sources might contain contradicting information

### Formatting Looks Wrong

If your formatted content doesn't display correctly:

* Avoid excessive nesting (too many sub-headings)
* Keep formatting simple - basic bold, italic, lists, and headings work best
* Test long content in the editor preview before saving

***

## Next Steps

<CardGroup>
  <Card title="Web Sources" icon="globe" href="/sources/web-sources">
    Import content from your website pages.
  </Card>

  <Card title="Q&A Sources" icon="circle-question" href="/sources/qa-sources">
    Create targeted question-answer pairs for precise responses.
  </Card>

  <Card title="Test Your Agent" icon="flask" href="/agents/playground">
    Verify your text sources work in the Playground.
  </Card>

  <Card title="Sources Overview" icon="database" href="/sources/overview">
    Learn about all source types and best practices.
  </Card>
</CardGroup>


# Web Sources
Source: https://docs.cosmo.humanizing.com/sources/web-sources

Import content from your website using URLs, sitemaps, or automated crawling

## Overview

Web sources allow you to import content directly from your website into your agent's knowledge base. This is the most common way to train your agent on existing website content like product pages, documentation, blog posts, and service descriptions.

<Tip>
  Start with your most important pages first. Quality matters more than quantity - a focused knowledge base with relevant content performs better than one filled with irrelevant pages.
</Tip>

## Discovery Methods

The platform offers four methods to discover and import web content:

<CardGroup>
  <Card title="Quick Scan" icon="zap">
    Fast domain mapping that quickly discovers pages across your website.
  </Card>

  <Card title="Deep Scan" icon="layers">
    Thorough crawling with advanced options for precise control over what gets imported.
  </Card>

  <Card title="Sitemap Import" icon="file-lines">
    Import URLs directly from your website's sitemap.xml file.
  </Card>

  <Card title="Manual Entry" icon="clipboard">
    Paste specific URLs when you know exactly which pages to import.
  </Card>
</CardGroup>

***

## Quick Scan

Quick Scan is the fastest way to discover pages on your website. It uses intelligent domain mapping to find pages without fully crawling each one.

### How to Use

1. Select **Quick Scan** as your discovery method
2. Enter your website URL (e.g., `https://example.com`)
3. Click **Scan Domain**
4. Review the discovered URLs in the pending list
5. Save the pages you want to your agent's knowledge base

### Advanced Options

<Accordion title="URL Limit">
  By default, Quick Scan will discover unlimited pages. You can set a limit to cap the number of URLs discovered:

  * **Unlimited**: Discover all available pages
  * **Custom limit**: Set a specific number (e.g., 100 pages)

  This is useful when you have a large website but only need a subset of pages.
</Accordion>

***

## Deep Scan

Deep Scan provides thorough crawling with fine-grained control over the crawling process. Use this when you need precise control over which pages are discovered.

### How to Use

1. Select **Deep Scan** as your discovery method
2. Enter your starting URL (e.g., `https://example.com/docs`)
3. Configure advanced options (optional)
4. Click **Scan Domain**
5. Monitor the crawl progress in real-time
6. Review and save discovered URLs

### Advanced Options

Deep Scan offers several configuration options:

<AccordionGroup>
  <Accordion icon="arrow-down" title="Max Depth">
    Controls how many levels deep the crawler will follow links.

    | Depth | Behavior                                     |
    | ----- | -------------------------------------------- |
    | 0     | Only the starting URL                        |
    | 1     | Starting URL + pages linked from it          |
    | 2     | Starting URL + 2 levels of linked pages      |
    | 3+    | Continues following links to specified depth |

    **Default**: 2 levels

    <Note>Higher depth values result in more pages but longer crawl times.</Note>
  </Accordion>

  <Accordion icon="clock" title="Wait Time">
    Time in milliseconds to wait between requests. This helps avoid overwhelming your server and prevents rate limiting.

    **Default**: 200ms

    Increase this value if your server has rate limiting or if you're experiencing timeout errors.
  </Accordion>

  <Accordion icon="hashtag" title="URL Limit">
    Maximum number of URLs to discover during the crawl.

    * **Unlimited**: No cap on discovered URLs
    * **Custom limit**: Stop after discovering specified number of pages

    **Default**: 100 URLs
  </Accordion>

  <Accordion icon="globe" title="Domain Restriction">
    Controls whether the crawler stays on your domain or follows external links.

    | Option               | Behavior                                                |
    | -------------------- | ------------------------------------------------------- |
    | **Same Domain Only** | Only crawl pages on the same domain as the starting URL |
    | **All Domains**      | Follow links to external websites too                   |

    **Default**: Same Domain Only

    <Warning>Enabling "All Domains" can significantly increase crawl time and may include irrelevant content.</Warning>
  </Accordion>

  <Accordion icon="folder" title="Subpath Restriction">
    Limit crawling to specific paths on your website. Enter comma-separated paths to restrict the crawler.

    **Example**: `/docs, /blog, /products`

    This would only crawl URLs that contain `/docs`, `/blog`, or `/products` in their path.
  </Accordion>

  <Accordion icon="filter" title="Filtering Options">
    Additional filters to exclude unwanted URLs:

    | Filter                | What it excludes                           |
    | --------------------- | ------------------------------------------ |
    | **Skip Social Media** | Links to Facebook, Twitter, LinkedIn, etc. |
    | **Skip File URLs**    | Links to PDFs, images, downloads, etc.     |
    | **Skip Anchor Links** | URLs with `#` fragments                    |

    All filters are enabled by default.
  </Accordion>
</AccordionGroup>

### Canceling a Crawl

During a Deep Scan, you can click **Cancel** at any time to stop the crawl. Any URLs discovered up to that point will still be available in your pending list.

***

## Sitemap Import

If your website has a sitemap.xml file, you can import all URLs from it directly. This is often the most reliable method for well-maintained websites.

### How to Use

1. Select **Sitemap** as your discovery method
2. Enter your sitemap URL (e.g., `https://example.com/sitemap.xml`)
3. Click **Import Sitemap**
4. Review the parsed URLs
5. Save the pages you want

### Finding Your Sitemap

Common sitemap locations:

* `https://yoursite.com/sitemap.xml`
* `https://yoursite.com/sitemap_index.xml`
* `https://yoursite.com/sitemap/sitemap.xml`

<Tip>
  Check your website's `robots.txt` file - it often contains a link to your sitemap:

  ```
  Sitemap: https://yoursite.com/sitemap.xml
  ```
</Tip>

### Nested Sitemaps

The platform automatically handles **sitemap index files** - sitemaps that reference other sitemaps. When you import a sitemap index, it will:

1. Detect that it's an index file
2. Fetch each nested sitemap automatically
3. Combine all URLs into a single list
4. Support up to 3 levels of nesting

<Note>
  If your sitemap has more than 3 levels of nesting, some deeper sitemaps may be skipped. This limit helps prevent excessively long import times.
</Note>

***

## Manual URL Entry

When you know exactly which pages you want to import, manual entry is the fastest option.

### How to Use

1. Select **Manual** as your discovery method
2. Paste your URLs into the text area (one per line)
3. Click **Add URLs**
4. Review and save

### Supported Formats

The manual entry field accepts:

* Plain URLs (one per line)
* URLs with or without `https://` prefix
* Pasted HTML content (URLs will be automatically extracted)

**Example input:**

```
https://example.com/page-1
https://example.com/page-2
example.com/page-3
www.example.com/page-4
```

### Extracting URLs from HTML

If you copy HTML content (like from a webpage source), the platform will automatically extract all valid URLs from anchor tags and plain text.

<Tip>
  Use the **Parse from Clipboard** button to extract URLs from copied web content containing links.
</Tip>

***

## Managing Pending Sources

After discovering URLs using any method, they appear in the **Pending Sources** list where you can review and manage them before saving.

### Filtering Pending Sources

| Filter      | Purpose                                                             |
| ----------- | ------------------------------------------------------------------- |
| **Search**  | Find URLs containing specific text                                  |
| **Exclude** | Remove URLs matching patterns (e.g., `/admin`, `.pdf`)              |
| **Type**    | Filter by discovery method (Quick Scan, Deep Scan, Sitemap, Manual) |

### Duplicate Detection

The platform automatically detects duplicates:

| Status                     | Meaning                                    |
| -------------------------- | ------------------------------------------ |
| **NEW**                    | URL not in your knowledge base             |
| **Duplicate (in agent)**   | URL already exists in your agent's sources |
| **Duplicate (in pending)** | Same URL already in your pending list      |

Duplicates are shown in a separate section and can be cleared with one click.

### Saving Sources

Once you've reviewed your pending URLs:

1. Use filters to exclude unwanted pages
2. Click **Save to Agent** to add them to your knowledge base
3. Sources will begin processing automatically

***

## Best Practices

<AccordionGroup>
  <Accordion icon="bullseye" title="Start focused, then expand">
    Begin with your most important pages (product pages, key documentation, FAQs). Test your agent, then add more content as needed.
  </Accordion>

  <Accordion icon="sitemap" title="Use sitemaps when available">
    Sitemaps are maintained by your website and provide the most accurate list of pages. They're also faster than crawling.
  </Accordion>

  <Accordion icon="filter" title="Use exclusion filters liberally">
    Exclude admin pages, login pages, and irrelevant sections. Use patterns like `/admin`, `/login`, `/cart` in the exclude filter.
  </Accordion>

  <Accordion icon="clock" title="Be patient with large sites">
    Deep scans of large websites can take several minutes. The progress indicator shows real-time status.
  </Accordion>

  <Accordion icon="arrows-rotate" title="Re-import when content changes">
    When you update your website content, re-import the affected pages to keep your agent's knowledge current.
  </Accordion>
</AccordionGroup>

## Common Issues

### Crawl Times Out

If your crawl times out:

* Reduce the **Max Depth** setting
* Increase the **Wait Time** between requests
* Set a lower **URL Limit**
* Use **Subpath Restriction** to focus on specific sections

### Sitemap Won't Load

If sitemap import fails:

* Verify the sitemap URL is accessible in your browser
* Check that the sitemap is valid XML
* Ensure your server isn't blocking automated requests
* Try the direct sitemap URL (not the robots.txt reference)

### Missing Pages

If expected pages aren't discovered:

* Check if pages are linked from your starting URL
* Increase the **Max Depth** setting
* Verify pages aren't blocked by robots.txt
* Try using **Manual Entry** for specific pages

## Next Steps

<CardGroup>
  <Card title="Text Sources" icon="file-lines" href="/sources/text-sources">
    Add custom text content not on your website.
  </Card>

  <Card title="Q&A Sources" icon="circle-question" href="/sources/qa-sources">
    Create targeted question-answer pairs.
  </Card>

  <Card title="Test Your Agent" icon="flask" href="/agents/playground">
    Verify your knowledge base in the Playground.
  </Card>

  <Card title="Sources Overview" icon="database" href="/sources/overview">
    Learn about all source types and best practices.
  </Card>
</CardGroup>


# Voicebot Installation
Source: https://docs.cosmo.humanizing.com/voicebot/deployment

Connect your voicebot to a phone number and make it reachable for callers

## Introduction

After you have tested your voicebot in the Playground and assigned a phone number, it is ready to receive real calls. The assigned number is the direct line to your AI agent: when someone calls it, the voicebot answers with your configured first message and uses the same knowledge base as your chat agent.

You can make the voicebot reachable in two simple ways:

* **Use the assigned number directly** — publish the number on your website, contact page, help center, email signature, or other customer-facing material.
* **Forward your own number** — keep an existing business or local number and configure your phone system to forward calls to the assigned Cosmo number.

<Note>
  Call forwarding is supported by many phone systems, but the exact setup depends on your provider, PBX, or telecom configuration. We cannot document every phone system, but forwarding to the assigned Voicebot number is possible whenever your provider supports call forwarding.
</Note>

## Basic Installation Steps

<Steps>
  <Step title="Assign a Phone Number">
    Go to **Agent Settings → Voicebot** and select the phone number that should connect callers to this voicebot.
  </Step>

  <Step title="Test the Voicebot">
    Use the Voicebot Playground first, then place a real test call to confirm the greeting, voice, and answers feel right.
  </Step>

  <Step title="Choose How Callers Reach It">
    Decide whether to show the assigned number directly or forward an existing number to it.
  </Step>

  <Step title="Publish or Forward the Number">
    Add the assigned number to your customer-facing channels, or configure call forwarding in your phone system.
  </Step>
</Steps>

## Using the Assigned Number Directly

This is the fastest setup. Once the number is assigned to the voicebot, you can place it anywhere customers expect to find a phone contact option.

Common places include:

* Website header or footer
* Contact page
* Help center
* Booking or support pages
* Email signatures
* Printed material or QR-code destinations

## Forwarding Your Own Number

If you already have a public business number, you can keep using it. Configure that number to redirect or forward calls to the phone number assigned to your Cosmo Voicebot.

This is useful when you want callers to keep dialing a familiar number while the voicebot handles the conversation in the background.

<Tip>
  After enabling forwarding, call your public number from an external phone and confirm that the voicebot answers. This verifies both your phone-system forwarding and the Cosmo Voicebot configuration.
</Tip>

## Related Pages

<CardGroup>
  <Card title="Phone Numbers" icon="sim-card" href="/voicebot/phone-numbers">
    Purchase, manage, and assign phone numbers for your voicebot agents.
  </Card>

  <Card title="Voicebot Playground" icon="flask" href="/voicebot/playground">
    Test responses before making the number available to callers.
  </Card>
</CardGroup>


# Voicebot Overview
Source: https://docs.cosmo.humanizing.com/voicebot/overview

Enable Cosmo's Voicebot channel with automatic phone number provisioning

## What is the Voicebot?

The Voicebot is Cosmo's phone channel. When enabled, callers can phone a dedicated number and speak directly with your AI agent — the same agent that powers your Chatbot and Kiosk Avatar, trained on the same knowledge base.

<Note>
  Voicebot is included in **Standard, Pro, Large, and Enterprise** packages. Free trial users can access it during the trial period. Once the trial ends, an active eligible package is required to keep voice calls enabled.
</Note>

## When to Use It

* **Inbound support calls** — let customers call a number instead of (or alongside) using the chat widget
* **Automated voice responses** — handle FAQs, bookings, or routing over the phone without a human agent
* **Multilingual phone support** — serve callers in their language using the same multilingual setup as your chatbot

## How It Fits With Your Other Channels

Voicebot, Chatbot, and Kiosk Avatar are channels of the same AI agent. You enable them per agent from the agent settings.

| Channel          | Interface            | Use Case                               |
| ---------------- | -------------------- | -------------------------------------- |
| **Chatbot**      | Embedded chat widget | Website visitors, text-based support   |
| **Kiosk Avatar** | Full-screen kiosk    | In-person visitor check-in             |
| **Voicebot**     | Phone call           | Callers via a provisioned phone number |

All three share the same knowledge base and Q\&A sources. Changes to your sources apply across all channels instantly.

## Data Processing and Caller Information

The Voicebot handles voice input and generated speech. It can also create transcripts and call time or duration metadata. Optional recording and routing features need additional, accurate information in your privacy notice.

Before launch, your organization must:

* Conclude the AVV with Humanizing
* Clearly tell callers that they are interacting with an AI system
* Provide your organization's privacy notice at the relevant interface
* Define the purpose, legal basis, retention period, and deletion process
* Check the rules that apply to telephone services, recording, consent, caller identification, and emergency communications

<Card title="Voicebot Data Processing" icon="shield-check" href="/data-protection/overview">
  Review the GDPR role split, Voicebot data categories, AVV request, and privacy-notice template.
</Card>

## What You Need to Get Started

<Steps>
  <Step title="Assign a Phone Number">
    Purchase a phone number from the workspace Phone Numbers page or assign one that's already been provisioned. The number is what callers will dial.
  </Step>

  <Step title="Set a First Message">
    Write the greeting your agent speaks when a caller connects — for example, "Hi, thanks for calling. How can I help you today?"
  </Step>

  <Step title="Choose a Voice">
    Select one of the available ElevenLabs voices. Each voice has a human-readable label like "Sarah - Warm & Professional" so you can match the tone to your brand.
  </Step>
</Steps>

<Tip>
  Voicebot settings are created automatically when you create a new agent — you don't need a separate setup step. Go to **Agent Settings → Voicebot** to configure and enable it.
</Tip>

## Voicebot Settings Field Order

When configuring the Voicebot, the fields appear in this order:

1. **Name** — the display name for this voicebot configuration
2. **Phone number** — the number callers will dial (assigned from your workspace)
3. **First message** — the greeting spoken when a call connects
4. **Voice** — the ElevenLabs voice used for all responses

## Getting Started

<CardGroup>
  <Card title="Phone Numbers" icon="sim-card" href="/voicebot/phone-numbers">
    Purchase and manage phone numbers for your voicebot agents.
  </Card>

  <Card title="Install Voicebot" icon="phone-call" href="/voicebot/deployment">
    Make your voicebot reachable through an assigned or forwarded phone number.
  </Card>

  <Card title="Test in Playground" icon="flask" href="/voicebot/playground">
    Use the playground to test your voicebot responses without making a real call.
  </Card>
</CardGroup>


# Phone Numbers
Source: https://docs.cosmo.humanizing.com/voicebot/phone-numbers

Purchase and manage phone numbers for your voicebot agents

## How Phone Numbers Work

Phone numbers are managed at the **workspace level** — not per agent. You purchase numbers once and assign them to any voicebot agent in the workspace.

This means you can:

* Buy multiple numbers (e.g., one per country or department)
* Reassign a number from one agent to another without re-purchasing
* Keep unused numbers provisioned for future use

## Purchasing a Phone Number

<Steps>
  <Step title="Go to Phone Numbers">
    Navigate to **Workspace Settings → Phone Numbers**.
  </Step>

  <Step title="Search for a Number">
    Select a country and optionally enter an area code or prefix to filter available numbers.
  </Step>

  <Step title="Buy with One Click">
    Click **Purchase** next to any available number. The number is provisioned and added to your workspace immediately.
  </Step>
</Steps>

<Note>
  Numbers are auto-registered to your workspace as soon as the purchase completes. No manual activation or porting is required.
</Note>

## Assigning a Number to an Agent

Once a number is in your workspace, assign it from the agent's voicebot settings:

1. Open the agent and go to **Agent Settings → Voicebot**
2. In the **Phone number** field, select the number from the dropdown
3. Save your settings

Each phone number can only be assigned to one agent at a time. If you need to reassign a number, remove it from the current agent first.

## Pricing

Voicebot is included in Standard, Pro, Large, and Enterprise packages. Connected calls consume **100 credits per started minute** from your package allowance. Calls that ring but are not answered do not consume credits.

<Tip>
  Check your current usage and remaining balance in **Workspace Settings → Billing**. You can set up alerts to be notified before your balance runs low.
</Tip>

<Warning>
  If your balance reaches zero during a call, the call ends gracefully. New calls will not connect if there is insufficient balance to cover at least one minute.
</Warning>


# Voicebot Playground
Source: https://docs.cosmo.humanizing.com/voicebot/playground

Test your voicebot's responses and knowledge base without making a real phone call

## What the Playground Does

The Voicebot playground lets you test how your agent responds to callers before going live. You can check answers, verify knowledge base retrieval, and refine your first message — all without a phone or microphone.

## Text Chat Mode

The playground includes a **text chat mode** that simulates a voice conversation by typing. Send messages as if you were speaking, and the agent responds as it would on a real call.

<Tip>
  Text chat mode is the fastest way to test. No microphone, no phone number required — just type and read the response.
</Tip>

Use text chat mode to:

* Test how the agent handles specific questions
* Verify that knowledge base sources are returning accurate answers
* Check edge cases before exposing the number to callers

## Audio Playback

When the agent replies, you can play back the response as audio to hear exactly what callers will hear — including the selected voice, pacing, and pronunciation.

This is especially useful for:

* Verifying the **first message** sounds natural when spoken aloud
* Catching awkward phrasing that reads fine in text but sounds odd as speech
* Confirming the selected voice matches your brand tone

## Testing Knowledge Base and RAG Responses

The playground queries the same knowledge base your live voicebot uses. Ask questions a caller might ask and confirm:

* The correct source is being retrieved
* The answer is accurate and complete
* The response is an appropriate length for a voice reply (shorter is usually better)

<Note>
  If a response is too long or too detailed for voice, consider adding a Q\&A source with a shorter, voice-optimized answer for that question. Q\&A sources take priority over web-scraped content.
</Note>

## How to Access the Playground

1. Open the agent and go to the **Playground** tab
2. Select **Voicebot** mode from the mode switcher
3. Type a message in the input field and press Enter
4. Click the play button on any response to hear the audio


# Billing & Subscription
Source: https://docs.cosmo.humanizing.com/workspace/billing

Understand your free trial, plans, credits, and how to manage your subscription

## Free Trial

Every new workspace starts with a 14-day free trial — no credit card required.

During the trial you get:

* **14 days** of full platform access
* **5,000 credits** to use across your agents
* Access to all features, including Voicebot

<Note>
  When your trial ends, your agents will stop responding until you subscribe to a paid plan. Your data and configuration are not deleted — subscribing restores access immediately.
</Note>

You can monitor your remaining trial days and credit usage on the **Billing** settings page at any time.

## Subscribing to a Plan

To subscribe after your trial — or at any point during it:

<Steps>
  <Step title="Open Billing Settings">
    Go to **Settings** → **Billing** in the left sidebar.
  </Step>

  <Step title="Choose a Plan">
    Select the plan that fits your usage. Toggle between **monthly** and **yearly** billing — yearly plans are offered at a discount.
  </Step>

  <Step title="Complete Checkout">
    Click **Subscribe** to open Stripe Checkout. Enter your payment details and confirm. Your subscription activates immediately.
  </Step>
</Steps>

<Tip>
  Yearly billing reduces your effective monthly cost. If you expect sustained usage, it is usually the better choice.
</Tip>

## Credits

Credits are the unit of usage in Cosmo by Humanizing. Every interaction your agents handle consumes credits from the monthly allowance included in your package.

### What Consumes Credits

| Feature               | Credit Cost                                 |
| --------------------- | ------------------------------------------- |
| **Chatbot message**   | 10 credits per message                      |
| **Kiosk Avatar call** | 50 credits per started minute of call time  |
| **Voicebot call**     | 100 credits per started minute of call time |

<Note>
  Voicebot is included in Standard, Pro, Large, and Enterprise packages. Connected Voicebot calls consume credits from the package allowance; there is no separate per-minute Voicebot line item.
</Note>

### Tracking Your Usage

Your current credit balance and a usage chart are available on the **Billing** settings page. The chart shows consumption over time so you can spot usage trends before you run out.

## Managing Your Subscription

### Upgrading or Downgrading

You can change your plan at any time from **Settings** → **Billing**:

* **Upgrades** take effect immediately. You are charged a prorated amount for the remainder of the current billing period.
* **Downgrades** take effect at the end of your current billing period. You keep your current plan's limits until then.

<Note>
  Voicebot is included from Standard onward. If you downgrade to Hobby, Voicebot access is removed when the downgrade takes effect.
</Note>

### Payment Method and Invoices

Click **Manage Billing** on the Billing settings page to open the Stripe billing portal. From there you can:

* Update your payment method
* Download past invoices
* View upcoming charges

### Cancelling Your Subscription

To cancel, open the Stripe billing portal via **Manage Billing** and follow the cancellation steps. Your subscription remains active until the end of the paid period — you will not be charged again after that.

<Warning>
  After cancellation, your agents stop responding once the paid period ends. Your workspace data is retained, so you can resubscribe later without losing your configuration.
</Warning>

## Overusage & Credit Warnings

### Overusage Toggle

By default, your agents stop responding when your monthly credits are exhausted. You can change this:

* **Overusage on** — your agents continue running after credits run out. Additional usage is charged at the overage rate for your plan.
* **Overusage off** — your agents pause automatically when credits reach zero. No unexpected charges.

Toggle this setting from the **Billing** settings page.

<Tip>
  If uninterrupted availability matters for your use case, enable overusage and monitor your usage chart regularly to avoid unexpected bills.
</Tip>

### Low Credit Warnings

When your credit balance drops below the warning threshold, you will receive an in-app notification. This gives you time to either upgrade your plan, top up, or review your agent usage before credits run out.

The warning threshold is set automatically based on your plan.


# Team Members
Source: https://docs.cosmo.humanizing.com/workspace/members

Learn how to invite team members, manage roles, and collaborate within your workspace

## Overview

Team member management allows you to collaborate with others by inviting them to your workspace. Each member is assigned a role that determines their permissions and what actions they can perform.

<Info>
  Only workspace owners and admins can invite new members and manage existing team members. Members have view-only access to the team roster.
</Info>

## Roles and Permissions

Your workspace supports three roles, each with different permission levels:

### Role Hierarchy

| Role       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| **Owner**  | Full control over the workspace, including deletion and all administrative actions |
| **Admin**  | Can manage members, invitations, and most workspace settings                       |
| **Member** | Can view and use agents, but cannot manage team or workspace settings              |

### Detailed Permissions

| Action                   | Owner | Admin | Member |
| ------------------------ | ----- | ----- | ------ |
| View workspace settings  | ✓     | ✓     | ✓      |
| View team members        | ✓     | ✓     | ✓      |
| Create and manage agents | ✓     | ✓     | ✓      |
| Manage knowledge sources | ✓     | ✓     | ✓      |
| View conversations       | ✓     | ✓     | ✓      |
| Invite new members       | ✓     | ✓     | ✗      |
| Remove members           | ✓     | ✓     | ✗      |
| Cancel invitations       | ✓     | ✓     | ✗      |
| Update workspace name    | ✓     | ✗     | ✗      |
| Delete workspace         | ✓     | ✗     | ✗      |

<Tip>
  When inviting new members, consider what level of access they need. Most team members only need the **Member** role to use and manage agents effectively.
</Tip>

## Accessing Team Members

To access team member management:

<Steps>
  <Step title="Open Settings">
    Click on **Settings** in the left sidebar navigation.
  </Step>

  <Step title="Select Members">
    Click on **Members** in the settings menu to open the team members page.
  </Step>
</Steps>

## Inviting Team Members

Invite new members to collaborate in your workspace by sending them an email invitation.

<Steps>
  <Step title="Navigate to Members">
    Go to **Settings** → **Members** from the sidebar.
  </Step>

  <Step title="Click Invite Member">
    Click the **Invite Member** button in the top right corner.
  </Step>

  <Step title="Enter Email Address">
    In the dialog that appears, enter the email address of the person you want to invite.
  </Step>

  <Step title="Select a Role">
    Choose the appropriate role for the new member:

    * **Member** - Standard access for most team members
    * **Admin** - For users who need to manage the team
  </Step>

  <Step title="Send Invitation">
    Click **Send Invitation** to send the email invite.
  </Step>
</Steps>

<Note>
  Invitations expire after a set period. If an invitation expires, you'll need to send a new one.
</Note>

### What the Invitee Receives

When you invite someone, they receive an email containing:

* The name of your workspace
* Your name as the inviter
* The role they've been assigned
* A link to accept the invitation

## Managing Pending Invitations

Pending invitations appear in a separate section below the current members list. These are invitations that have been sent but not yet accepted.

### Viewing Pending Invitations

Pending invitations are displayed with:

* The invitee's email address
* The assigned role
* The expiration date

### Canceling an Invitation

If you need to revoke an invitation before it's accepted:

<Steps>
  <Step title="Find the Invitation">
    Locate the pending invitation in the **Pending Invitations** section.
  </Step>

  <Step title="Click Cancel">
    Click the trash icon button next to the invitation.
  </Step>

  <Step title="Confirm Cancellation">
    Confirm the cancellation in the dialog that appears.
  </Step>
</Steps>

<Warning>
  Once an invitation is canceled, the invitee will no longer be able to use the invitation link. You'll need to send a new invitation if you want them to join.
</Warning>

## Removing Team Members

Owners and admins can remove members from the workspace when necessary.

<Steps>
  <Step title="Find the Member">
    In the **Current Members** section, locate the team member you want to remove.
  </Step>

  <Step title="Click Remove">
    Click the trash icon button next to their name.
  </Step>

  <Step title="Confirm Removal">
    In the confirmation dialog, review the member's name and click **Remove** to confirm.
  </Step>
</Steps>

### Important Considerations

<Warning>
  Removing a member immediately revokes their access to the workspace. They will no longer be able to view or manage any agents, sources, or conversations in this workspace.
</Warning>

| Item                 | What Happens            |
| -------------------- | ----------------------- |
| **Workspace Access** | Immediately revoked     |
| **Agents Created**   | Remain in the workspace |
| **Sources Added**    | Remain in the workspace |
| **Active Sessions**  | Terminated immediately  |

<Note>
  You cannot remove yourself from a workspace. If you're the owner and want to leave, you must first transfer ownership to another member or delete the workspace entirely.
</Note>

## Accepting an Invitation

When you receive a workspace invitation:

<Steps>
  <Step title="Check Your Email">
    Look for an invitation email from Cosmo by Humanizing.
  </Step>

  <Step title="Click the Invitation Link">
    Click the **Accept Invitation** button in the email.
  </Step>

  <Step title="Review Invitation Details">
    On the acceptance page, review the workspace name and your assigned role.
  </Step>

  <Step title="Accept or Decline">
    Click **Accept** to join the workspace, or **Decline** if you don't want to join.
  </Step>

  <Step title="Access Your New Workspace">
    After accepting, you'll be automatically redirected to the workspace. Use the workspace switcher in the header to switch between workspaces.
  </Step>
</Steps>

### New User Acceptance

If you don't have an existing account:

* An account will be automatically created using the email address the invitation was sent to
* You'll be signed in automatically after accepting
* You can set up your profile and password in Account Settings

### Existing User Acceptance

If you already have an account:

* You must be signed in with the same email address the invitation was sent to
* The new workspace will be added to your workspace list
* You can switch between workspaces using the workspace switcher

<Warning>
  Invitations are tied to a specific email address. If you try to accept an invitation while signed in with a different email, you'll see an email mismatch error.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="envelope" title="Invitee didn't receive the email">
    Ask them to check their spam or junk folder. If it's not there, cancel the invitation and send a new one. Make sure the email address is spelled correctly.
  </Accordion>

  <Accordion icon="clock" title="Invitation has expired">
    If an invitation has expired, it can no longer be used. Cancel the expired invitation and send a new one to the same email address.
  </Accordion>

  <Accordion icon="user-slash" title="Cannot remove a member">
    You cannot remove:

    * Yourself from the workspace
    * The workspace owner (unless you are the owner)

    If you need to transfer ownership, contact your workspace owner.
  </Accordion>

  <Accordion icon="envelope-open" title="Email mismatch when accepting">
    The invitation email must match the email you're signed in with. Either:

    * Sign out and sign in with the correct email
    * Ask for a new invitation to your current email address
  </Accordion>

  <Accordion icon="user-plus" title="Invite button is disabled">
    You may not have permission to invite members. Only owners and admins can send invitations. Contact your workspace owner if you need to invite someone.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Use Appropriate Roles" icon="shield-check">
    Assign the minimum role needed for each team member's responsibilities. Most users only need Member access.
  </Card>

  <Card title="Review Periodically" icon="calendar-check">
    Regularly review your team members and remove any who no longer need access to maintain security.
  </Card>

  <Card title="Communicate Changes" icon="comments">
    Notify team members before removing them so they can save any information they need from the workspace.
  </Card>

  <Card title="Track Pending Invitations" icon="list-check">
    Follow up on pending invitations that haven't been accepted after a few days to ensure invitees received the email.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Workspace Settings" icon="gear" href="/workspace/settings">
    Learn about other workspace configuration options.
  </Card>

  <Card title="Create an Agent" icon="robot" href="/agents/onboarding">
    Start building AI agents for your team to use.
  </Card>
</CardGroup>


# Workspace Settings
Source: https://docs.cosmo.humanizing.com/workspace/settings

Learn how to manage your workspace, including renaming and deleting workspaces

## Overview

Workspace settings allow you to manage your workspace configuration, including updating your workspace name and permanently deleting the workspace when it's no longer needed.

<Info>
  Only workspace owners have access to all settings. Admins and members have limited access based on their role.
</Info>

## Accessing Workspace Settings

To access your workspace settings:

<Steps>
  <Step title="Open Settings">
    Click on **Settings** in the left sidebar navigation.
  </Step>

  <Step title="Select Workspace">
    Click on **Workspace** in the settings menu to open the workspace settings page.
  </Step>
</Steps>

## Workspace Information

The workspace information section displays your current workspace name and allows you to update it.

### Renaming Your Workspace

You can change your workspace name at any time to better reflect its purpose or organization:

<Steps>
  <Step title="Navigate to Workspace Settings">
    Go to **Settings** → **Workspace** from the sidebar.
  </Step>

  <Step title="Edit the Name">
    In the **Workspace Information** card, update the **Workspace Name** field with your new name.
  </Step>

  <Step title="Save Changes">
    Click **Save Changes** to update the workspace name.
  </Step>
</Steps>

<Tip>
  Choose a descriptive name that clearly indicates the workspace's purpose. This helps team members quickly identify the right workspace when switching between multiple workspaces.
</Tip>

### Workspace Name Guidelines

When naming your workspace, keep these guidelines in mind:

| Guideline                 | Description                                                                 |
| ------------------------- | --------------------------------------------------------------------------- |
| **Be descriptive**        | Use names like "Marketing Team", "Customer Support", or "Acme Corp Project" |
| **Keep it concise**       | Names should be easy to read and recognize at a glance                      |
| **Use consistent naming** | If you have multiple workspaces, use a consistent naming convention         |

## Danger Zone

The danger zone contains irreversible actions that can permanently affect your workspace. These options are highlighted with a red border to indicate their critical nature.

### Deleting a Workspace

<Warning>
  Deleting a workspace is permanent and cannot be undone. All agents, knowledge sources, conversations, and data associated with the workspace will be permanently deleted.
</Warning>

Only workspace **owners** can delete a workspace. Before deleting, consider:

* Have you exported any important data or conversations?
* Are there team members who still need access to the agents?
* Is there any content you want to preserve?

#### Steps to Delete a Workspace

<Steps>
  <Step title="Open Workspace Settings">
    Navigate to **Settings** → **Workspace**.
  </Step>

  <Step title="Locate the Danger Zone">
    Scroll down to find the **Danger Zone** section highlighted with a red border.
  </Step>

  <Step title="Click Delete">
    Click the **Delete** button next to "Delete Workspace".
  </Step>

  <Step title="Confirm Deletion">
    A confirmation dialog will appear. To proceed:

    * Read the warning message carefully
    * Type the exact workspace name in the confirmation field
    * Click **Delete Workspace** to confirm
  </Step>
</Steps>

<Note>
  Copy-pasting the workspace name into the confirmation field is disabled for safety. You must type the name manually to confirm deletion.
</Note>

#### What Happens When You Delete a Workspace

When a workspace is deleted:

| Item                  | What Happens                                        |
| --------------------- | --------------------------------------------------- |
| **Agents**            | All agents in the workspace are permanently deleted |
| **Knowledge Sources** | All web, text, and Q\&A sources are removed         |
| **Conversations**     | Chat history and conversation data are deleted      |
| **Team Members**      | All member access is revoked immediately            |
| **Settings**          | Widget configurations and customizations are lost   |

After deletion, you'll be redirected to:

* **Create Workspace** page if you have no other workspaces
* **Agents** page of another workspace if you belong to multiple workspaces

## Permissions Overview

Different roles have different access to workspace settings:

| Action                  | Owner | Admin | Member |
| ----------------------- | ----- | ----- | ------ |
| View workspace settings | Yes   | Yes   | Yes    |
| Rename workspace        | Yes   | No    | No     |
| Delete workspace        | Yes   | No    | No     |
| Manage team members     | Yes   | Yes   | No     |

<Info>
  For detailed information about managing team members and invitations, see the [Team Members](/workspace/members) documentation.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="lock" title="Cannot access workspace settings">
    Make sure you're signed in and have selected the correct workspace from the workspace dropdown. If you still can't access settings, you may not have the required permissions.
  </Accordion>

  <Accordion icon="floppy-disk" title="Changes not saving">
    If your changes aren't saving, check your internet connection and try again. If the problem persists, refresh the page and re-enter your changes.
  </Accordion>

  <Accordion icon="trash" title="Delete button is disabled">
    The delete button may be disabled if:

    * You don't have owner permissions
    * A delete operation is already in progress
    * There's a temporary system issue
  </Accordion>

  <Accordion icon="input-text" title="Confirmation text not matching">
    When deleting a workspace, you must type the workspace name exactly as shown, including capitalization and spaces. Copy-paste is disabled for safety.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup>
  <Card title="Backup Before Deleting" icon="download">
    Before deleting a workspace, export any important conversation data or agent configurations you may need later.
  </Card>

  <Card title="Communicate with Team" icon="comments">
    If you're deleting a shared workspace, notify team members in advance so they can save any information they need.
  </Card>

  <Card title="Use Descriptive Names" icon="tag">
    Keep workspace names clear and descriptive to help team members identify the right workspace quickly.
  </Card>

  <Card title="Review Before Confirming" icon="eye">
    Always double-check that you're deleting the correct workspace. The confirmation step exists to prevent accidental deletions.
  </Card>
</CardGroup>

## Getting Help

A **Help** section is available in the sidebar directly below Settings. Use it to contact the Humanizing support team without leaving the app.

<CardGroup>
  <Card title="Report a Bug" icon="bug">
    Describe unexpected behavior. The form opens pre-filled for a bug report and supports screenshots (paste or upload) and file attachments.
  </Card>

  <Card title="Request a Feature" icon="lightbulb">
    Share an idea or improvement. The form opens pre-filled for a feature request. You can switch between request types inside the form.
  </Card>
</CardGroup>

<Tip>
  The Help section is available both in the workspace sidebar and in the agent detail sidebar so you can reach support from wherever you are in the app.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Manage Team Members" icon="users" href="/workspace/members">
    Learn how to invite team members and manage their roles.
  </Card>

  <Card title="Create an Agent" icon="robot" href="/agents/onboarding">
    Build your first AI agent for your workspace.
  </Card>
</CardGroup>