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 'widget agent' (or the specific agent you wish to embed) 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.

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

<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 styles are scoped to the widget container, so you should target #katara-widget-container * or a more specific selector if needed, or simply use :root.

Example:

<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-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.