# Website Widget

This agent allows you to embed a customizable support bot into your website. You have full control over the look, feel, and responses of the widget.

## Generating the widget embed code

To get a preconfigured `<script>` tag for embedding the Katara Website Widget, follow these steps within the Katara application:

1. **Navigate to the Agent Library**: This is the default page you land on after signing in.
2. **Select Your Agent**: Click on the a Website Widget agent from the list of agents available to your organization.
3. **Go to 'Embed Widget' Tab**: Once on the agent's page, select the 'Embed Widget' tab.
4. **Specify Allowed Domain**:
   * Enter the domain where you plan to deploy the widget (e.g., `yourwebsite.com`).
   * **Note**: The widget will also function in a local development environment when served from `localhost:3000`.
5. **Configure Access Grant**:
   * You can either select an existing access grant that is already configured for the specified domain.
   * Or, create a new access grant using the options provided in the dropdown menu.

Once these steps are completed, the Katara application will generate the `<script>` tag with the necessary `data-katara-agent-id` and `data-katara-token` pre-filled for your specific agent and domain. You can then copy this script tag and paste it into your website's HTML.

On this page, you will also be given some code labeled "Importmap and base styles." You must place these into the `<head>` tag of your site for the widget to function and have the correct styling.

This document also describes the additional HTML data attributes and CSS custom properties that can be used to further configure and style the Katara Website Widget.

## Widget Configuration

### Data Attributes

**`data-katara-agent-id` (Required)**

* **Type**: `String`
* **Description**: The unique identifier for the Katara agent that the widget will interact with. This ID is provided when you create an agent in the Katara dashboard.
* **Example**: `data-katara-agent-id="<your-agent-id>"`

**`data-katara-token` (Required)**

* **Type**: `String`
* **Description**: The authentication token required to communicate with the Katara API. This token is associated with your organization and domain and is necessary for the widget to function.
* **Example**: `data-katara-token="<your-api-token>"`

**`data-title` (Optional)**

* **Type**: `String`
* **Default**: `"Katara AI"`
* **Description**: The title displayed at the top of the widget. If not provided, it defaults to "Katara AI".
* **Example**: `data-title="My Support Bot"`

**`data-user-prompt` (Optional)**

* **Type**: `String`
* **Default**: If not provided, the widget might use a default prompt like "Hello! How can I help you today?" or rely on the agent's configuration.
* **Description**: An initial prompt or question that is pre-filled for the user in the chat interface. This can be used to guide the user or suggest a common starting point.
* **Example**: `data-user-prompt="Hello! How can I help you today?"`

**`data-custom-logo-url` (Optional)**

* **Type**: `String`
* **Description**: The URL of a custom logo to be displayed in the widget header. If provided, this logo will replace the default Katara logo. The URL should point to a publicly accessible image.
* **Example**: `data-custom-logo-url="https://your-logo-url.com/logo.png"`

#### Example Usage

```html
<script
  src="<url-to-your-widget-script>"
  data-katara-agent-id="your-agent-id-here"
  data-katara-token="your-api-token-here"
  data-title="Customer Support"
  data-user-prompt="Hello! How can I help you today?"
  data-custom-logo-url="https://your-logo-url.com/logo.png"
  async
  defer
></script>
```

### Styling Customization

The appearance of the Katara Website Widget can be customized using CSS Custom Properties. You can override these properties by defining them in your own stylesheet or in a `<style>` tag in your HTML, ensuring they are defined before the widget script is loaded. The widget has default styles scoped to `#katara-widget-container` , but you can override these defaults anywhere in your CSS.

Example:

```html
<style>
  #katara-widget-container {
    --katara-widget-primary-color: #FF0000; /* Override primary color to red */
    --katara-widget-primary-bg-color: #FAFAFA; /* Override background to a light gray */
  }
</style>
```

#### Available CSS Custom Properties

| Variable                                   | Default Value                                | Description                                                                   |
| ------------------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------- |
| `--katara-widget-primary-color`            | `#2563EB`                                    | The primary color used for buttons, user messages, and other accents.         |
| `--katara-widget-primary-hover-color`      | `#1D4ED8`                                    | The hover color for elements using the primary color.                         |
| `--katara-widget-text-on-primary-color`    | `#FFFFFF`                                    | The text color used on elements with the primary color as their background.   |
| `--katara-widget-primary-bg-color`         | `#FFFFFF`                                    | The main background color of the widget.                                      |
| `--katara-widget-text-on-primary-bg-color` | `#374151`                                    | The text color used on top of the background color of the widget.             |
| `--katara-widget-border-color`             | `#E5E7EB`                                    | The color used for borders within the widget.                                 |
| `--katara-widget-user-msg-bg-color`        | `var(--katara-widget-primary-color)`         | The background color for messages sent by the user.                           |
| `--katara-widget-bot-msg-bg-color`         | `#F3F4F6`                                    | The background color for messages sent by the bot/agent.                      |
| `--katara-widget-user-msg-font-color`      | `var(--katara-widget-text-on-primary-color)` | The font color for messages sent by the user.                                 |
| `--katara-widget-bot-msg-text-color`       | `#1F2937`                                    | The font color for messages sent by the bot/agent.                            |
| `--katara-widget-msg-border-radius`        | `0.5rem`                                     | The border radius for chat message bubbles.                                   |
| `--katara-widget-ui-border-radius`         | `0.5rem`                                     | The border radius for main UI elements like the widget container and buttons. |
| `--katara-widget-position-right`           | `1rem`                                       | The distance of the widget from the right edge of the screen.                 |
| `--katara-widget-position-bottom`          | `1rem`                                       | The distance of the widget from the bottom edge of the screen.                |
| `--katara-widget-z-index`                  | `50`                                         | The stack order (z-index) of the widget.                                      |
| `--katara-widget-w-default`                | `20rem`                                      | The width of the widget in its default (non-expanded) state.                  |
| `--katara-widget-h-default`                | `24rem`                                      | The height of the widget in its default (non-expanded) state.                 |
| `--katara-widget-w-expanded`               | `50vw`                                       | The width of the widget in its expanded state.                                |
| `--katara-widget-h-expanded`               | `50vh`                                       | The height of the widget in its expanded state.                               |
| `--katara-widget-font-family`              | `system-ui,...`                              | The global font family for the widget.                                        |
| `--katara-widget-header-font-size`         | `0.875rem`                                   | Font size for the widget header title.                                        |
| `--katara-widget-header-font-weight`       | `500`                                        | Font weight for the widget header title.                                      |
| `--katara-widget-header-font-style`        | `normal`                                     | Font style (e.g., normal, italic) for the widget header title.                |
| `--katara-widget-chat-msg-font-size`       | `0.875rem`                                   | Font size for chat messages.                                                  |
| `--katara-widget-chat-msg-font-weight`     | `400`                                        | Font weight for chat messages.                                                |
| `--katara-widget-chat-msg-font-style`      | `normal`                                     | Font style for chat messages.                                                 |
| `--katara-widget-input-font-size`          | `0.875rem`                                   | Font size for the text input field.                                           |
| `--katara-widget-input-font-weight`        | `400`                                        | Font weight for the text input field.                                         |
| `--katara-widget-input-font-style`         | `normal`                                     | Font style for the text input field.                                          |


---

# 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://docs.katara.ai/about/agents/conversational/website-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.
