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

# Widget Installation

> Embed the Deflect chat widget on your website

The **Chat Widget** is how your users interact with the AI agent on your website. This guide covers generating the embed code, securing it with domain whitelisting, and customizing its behavior.

<Note>
  **New to Deflect?** Start with **[Launch an agent on your website](/launch-on-your-website)** for a full checklist from first login to a verified live widget.
</Note>

## Generating the embed snippet

<Steps>
  <Step title="Navigate to Settings">
    Go to **Settings** → **Widget** tab in your dashboard.
  </Step>

  <Step title="Create an API Key">
    If you haven't already, click **Create API Key**, give it a name (e.g., "Production Website"), and click **Create**.

    <Warning>
      Copy your API key immediately — it won't be shown again in full after creation.
    </Warning>
  </Step>

  <Step title="Select Your Chatbot">
    Choose which chatbot the widget should be connected to from the dropdown.
  </Step>

  <Step title="Copy the Snippet">
    The embed snippet will be generated automatically. Click **Copy** to copy it to your clipboard.
  </Step>

  <Step title="Paste into Your Website">
    Add the snippet just before the closing `</body>` tag in your website's HTML:

    ```html theme={null}
    <script
      src="https://widget.deflect.in/widget.js"
      data-api-key="YOUR_API_KEY"
      data-chatbot-id="YOUR_CHATBOT_ID"
    ></script>
    ```
  </Step>
</Steps>

## Domain Whitelisting

For security, you should restrict which domains can use your API key.

1. Go to **Settings** → **Domains** tab.
2. Click **Add Domain**.
3. Enter your website domain (e.g., `example.com`).
4. Click **Add**.

Only requests from **whitelisted** domains are accepted. The browser sends an **`Origin`** header; it must match a domain you added under **Settings → Domains**, or the widget cannot connect (including WebSocket chat).

<Warning>
  You must add **at least one** domain before the embedded widget will work on your site. With **no** domains whitelisted, widget traffic is **rejected**.
</Warning>

## Widget Customization

### Welcome Message

Configure the initial greeting users see when they open the chat:

* **Static**: A fixed message you define (e.g., "Hi! How can I help you today?").
* **Dynamic**: An AI-generated greeting based on context.

Set this in the **Agent Editor** under the agent's settings.

### Auto-Open

Enable auto-open to have the widget automatically open when a user visits your site:

* Go to **Settings** → **Widget** tab.
* Toggle **Auto Open** on.

### AI Popup Greeting

Show a small popup message next to the chat icon to encourage interaction:

* Go to **Settings** → **Widget** tab.
* Toggle **AI Greeting Popup** on.

The popup will display a contextual message to draw users into the chat.

<Frame caption="Product screenshot: widget with popup greeting (replace if your branding refresh makes this outdated).">
  <img src="https://mintcdn.com/quensultingai/Vk0F3QdCtadjJvc9/images/widget-preview.png?fit=max&auto=format&n=Vk0F3QdCtadjJvc9&q=85&s=a7b7ea340923520a07c23b12d2ceae41" alt="Chat widget on a website showing the popup greeting and chat window" width="456" height="224" data-path="images/widget-preview.png" />
</Frame>

## Visitor image uploads (web widget)

For agents that run on your **website**, you may enable **image uploads** so visitors can send screenshots or photos (for example, an error dialog). When enabled, images are validated and the assistant can use a **text description** of the image in context. Leave the feature off if you want strictly text-only conversations.

Configure per agent in the **Agent editor** (look for an images / uploads toggle for the web channel). Availability can depend on your **plan**.

## Testing

Before going live, use the **Preview Widget** to test the full user experience:

1. Go to the **Agent Editor** for your chatbot.
2. Use the built-in chat window on the right to test responses.
3. Or go to **Settings** → **Widget** and click **Preview** to see the widget exactly as users will.

<Tip>
  Always test after making changes to system prompts, knowledge base, or widget settings.
</Tip>