# Add a Widget

In the Website Embed channel, select **Add Widget**.

<div align="center" data-with-frame="true"><img src="/files/d5fc5cd56424eb18b33296700343508cf11ad6bc" alt="" width="375"></div>

On the widget setup page, enter the widget details and configure settings using the left panel. Review the live preview on the right as changes are made, then complete the setup.&#x20;

Widget configuration includes three sections: [Appearance](#appearance), [Behavior](#behavior), and [Advanced](#advanced).

<div data-with-frame="true"><img src="/files/1b67eedc2bae0c542749d2c740bac969e29c66c2" alt=""></div>

{% hint style="info" %}
Navigation tab — use this tab to move between [Appearance](#appearance), [Behavior](#behavior), and [Advanced](#advanced), and quickly review or update specific sections.

![](/files/tgngI0McFHLCpQhEeBwS)
{% endhint %}

{% stepper %}
{% step %}

### Appearance

**Control the visual design of the widget, including name, colors, and placement on the page.**

<div data-with-frame="true"><img src="/files/8b503c7307ffbbf2a2a4568a138bed59840119b0" alt=""></div>

Users can update the following fields:

1. **Basic Information**
   * **Company Display Name** — the public-facing name shown in the widget header.
   * **Widget Name** — an internal name used to manage multiple widgets.
   * **Welcome Messag**e — the greeting shown when the widget opens.

<div data-with-frame="true"><img src="/files/48d35360f532ea6efca8c087910b33a9aa72c4de" alt="" width="563"></div>

2. **Widget Color**

<div data-with-frame="true"><img src="/files/eee00c418e7aa4244277aa6dcff10ec899b1a0e0" alt="" width="563"></div>

* **Primary Color** — sets the primary color used across the widget and defines the overall brand look. This color applies to the header and the widget launcher and does not change when switching themes. A color can be selected in the color picker or entered as a HEX code.

![Header](/files/59f10ca85c8f18bdc835de6aeaa86c89ec1b9582) ![Launcher](/files/8ecb4fdf7fa1f147327801de64a5ceb364ed2b80)

* **Secondary Color** — sets the secondary color used for supporting UI elements and creates contrast with the primary color. This color applies only to the footer.

<div align="center"><img src="/files/6ea5eafcb8c579c998e7eccb27014491bdeb778e" alt="Footer" width="375"></div>

2. **Widget Theme**

   * To set the widget theme for the widget experience, choose the theme option that best matches the intended look and feel for visitors.
     * **Light** — applies light styling to the widget body and input field.
     * **Dark** — applies dark styling to the widget body, input field, and footer.
     * **Auto** — automatically sets the widget theme based on system settings.

   <div><figure><img src="/files/F6vPcCnOTvXRb6uqhilO" alt=""><figcaption><p>Light Theme</p></figcaption></figure> <figure><img src="/files/9cupOgFxD0n28cdeI7CU" alt=""><figcaption><p>Dark Theme</p></figcaption></figure></div>
3. **Position**
   * To set where the widget appears on the website, choose the position where it will be displayed for visitors (**Bottom Right**, **Bottom Left**, **Center**, or **Embedded**). This setting determines where the widget  shows up on the screen, or whether it appears inline where the widget is embedded on the page.

![Center](/files/bfcdb775cef7bfe38d321cca389897b0f5c1ccd4) ![Bottom Right](/files/6b41a29cc410744a3329e5dd6af5ef541f7ebc3e)

<div align="center"><img src="/files/92a9d718f74929ffa61a7aff429c465c1ecdc6a5" alt="Bottom Left" width="375"></div>
{% endstep %}

{% step %}

### Behavior

**Control how the widget interacts with visitors**

* **Human Handoff** — controls what happens when the bot needs to hand the conversation back to a live agent. If this setting is turned off, the conversation automatically closes when the bot attempts to route the chat to a human agent, instead of keeping the session open for a takeover.

<div data-with-frame="true"><figure><img src="/files/Nz016lw0pr2TPrIMUDrY" alt="" width="288"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Advanced

**Adjust technical and session settings**

* **Max Assistant Messages Per Session** — sets the maximum number of assistant messages allowed in a single chat session. When the limit is reached, the chat switches to a human user, and the status updates to **Pending 1st Response**.
* [**Session Timeout**](#session-times-out) **(minutes)** — sets how long a session stays active after the most recent message. The session stays active as long as messages continue. If no new message arrives within the set time (measured from the last message), the session expires and closes. If a human takes over during the session, the session remains active.

{% hint style="info" %}
The default values are 30 messages per session with a session timeout of 1,440 minutes (24 hours). These are the recommended settings. You can adjust these values based on preference.
{% endhint %}

<div data-with-frame="true"><figure><img src="/files/UTuJi7oUvNLuPfsCXCnV" alt="" width="291"><figcaption></figcaption></figure></div>

<details>

<summary>Session Timeout</summary>

* When the session times out, the widget prompts visitors to start a new conversation so chatting can continue after the previous session expires.

<p align="center"><img src="/files/LLLJYyfrJTno3p8h1UEp" alt=""></p>

* A timed-out session closes automatically in Chat and no longer appears as an active conversation.

<p align="center"><img src="/files/2VjyPB4itueQ9vSEAGlB" alt=""></p>

</details>
{% endstep %}

{% step %}

### Complete Configuration

After finishing configuration, select **Create**.

<div data-with-frame="true"><figure><img src="/files/d9JyTAfvboiNkwA5TDj5" alt="" width="245"><figcaption></figcaption></figure></div>
{% endstep %}

{% step %}

### Widget Activation

After a widget is created, the next page opens automatically so the widget details and activation steps can be reviewed.

<div data-with-frame="true"><figure><img src="/files/f6BUcEWvsk4HRGxpwQZZ" alt=""><figcaption></figcaption></figure></div>

1. In the Widget Configuration tab (in the middle of the page), confirm the widget status shows **Draft** (inactive).
2. In the **Embed Code** tab (at the bottom of the page), review the inactive reminder message.
3. To activate the widget, toggle it on in the top-right corner.

<div data-with-frame="true"><figure><img src="/files/UVYh1X18Ux7PfcsPROJE" alt=""><figcaption></figcaption></figure></div>

4. Confirm the widget status changes from **Draft** to **Active** and the inactive reminder message no longer appears.

<div data-with-frame="true"><figure><img src="/files/XEWu1kQCXRu8DgrWJrbU" alt=""><figcaption></figcaption></figure></div>
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://chatlyst.gitbook.io/chatlyst-user-guide/inbound-channels/website-embed/add-a-widget.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.