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

# Widget Configuration

> 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 cols={2}>
  <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 cols={2}>
  <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>