Skip to main content

Configuring UI

Widget Structure​

Main Areas​

The ChatBot widget consists of two primary sections: the Sidebar and the Chat Window.

The Sidebar, located on the left, serves multiple functions:

  • New Chat Button: Initiates a new chat session. If multiple agents are configured, it opens an agent selection popup.
  • Chat List: Displays a list of existing chat sessions. Clicking on a chat name within this list will display the related messages in the Chat Window.
  • Delete Button: Positioned next to each chat entry, this button allows users to delete the specific chat session.

Chat Window​

The Chat Window, located on the right, contains:

  • Message List: Displays the conversation history, grouped and sorted by the date of the last message in each chat.
  • Textarea Control: Positioned at the bottom, allowing users to input and send new messages.

Initialization Modes​

The ChatBot widget can be initialized in three different modes:

  1. Single Chat, Single Agent

    • The Sidebar is fully hidden.
    • Only the Chat Window is visible.

  2. Multiple Chats, Single Agent

    • Both the Sidebar and Chat Window are visible.
    • Clicking the "New Chat" button creates a new chat session immediately.

  3. Multiple Chats, Multiple Agents

    • Both the Sidebar and Chat Window are visible.
    • Clicking the "New Chat" button opens a list of available agents.
    • Selecting an agent initiates a new chat session.

These initialization modes allow for flexible configuration based on the requirements and agent availability.

UI Modes​

With or Without Sidebar​

To define whether the sidebar will be visible or hidden, set the sidebar property in the ChatBot configuration object. By default, the sidebar is set to true.

const chat = new ChatBot(node, { sidebar: true });

Single or Multiple Agents​

To provide a list of agents for the chat, use the agents property in the ChatBot configuration object. The agents property accepts an array of agent objects. Each agent object should include an id, a name, and optionally an avatar URL and a response handler.

Example usage:

const agents = [
    { id: 1, name: "Support Bot", avatar: "https://some.com/i.png" }
];
const chat = new ChatBot(node, { agents });

Data Format for Agents​

The agent data should follow the specified type definition:

type ResponseHandler = (data: Message[]) => Message | Promise<Message>;
type Agent = {
    id: TID;
    name: string;
    avatar?: string;
    response?: ResponseHandler;
}
  • id: Unique identifier for the agent.
  • name: Name of the agent.
  • avatar (optional): URL pointing to the agent's avatar image.
  • response (optional): A function that is triggered whenever the agent receives a new message in the chat. This function can return the response message directly or a promise that resolves to the response message.

The only mandatory field in the response message is msg.content, which represents the text of the response.

Example of a response handler:

const agent = {
    id: 2,
    name: "AI Bot",
    response: (data) => {
        return {
            content: "Hello, how can I assist you today?"
        };
    }
};

Render Modes​

The ChatBot widget supports various render modes to define the style of the chat area. The render mode determines how messages are displayed within the chat interface. The following render modes are available:

Render messages with "blocks" template​

The "blocks" template arranges messages in distinct block-like elements. This can be used for a clear and structured layout.

const chat = new ChatBot(node, { render: "blocks" });

Render messages with "bubbles" template​

The "bubbles" template displays messages inside bubble-shaped containers. This is similar to the appearance found in many popular messaging applications.

const chat = new ChatBot(node, { render: "bubbles" });

Render messages with "flow" template​

The "flow" template arranges messages in a continuous, flowing manner, creating a seamless and natural conversation style.

const chat = new ChatBot(node, { render: "flow" });

Render messages with "cards" template​

The "cards" template displays messages inside card-like containers, which can be useful for structuring more complex information or interactive content.

const chat = new ChatBot(node, { render: "cards" });

To initialize the ChatBot widget with any of these render modes, pass the desired render mode as an option when creating a new instance of ChatBot. The node parameter refers to the DOM node where the chat widget will be mounted.

Text Format Support​

The ChatBot widget allows for customization of message formats. Developers can choose between plain text and markdown formats for messages. The widget offers flexibility to render messages according to the specified format.

Using Plain Text Format​

To configure the ChatBot widget to use plain text format for messages, initialize the widget with the format property set to "text". The following code snippet demonstrates this configuration:

const chat = new ChatBot(node, { format: "text" });

In this setup, all messages sent and received through the ChatBot widget will be treated as plain text, without any special formatting.

Using Markdown Format​

To utilize markdown formatting for messages within the ChatBot widget, set the format property to "markdown" during initialization. Below is an example of how to configure the ChatBot widget for markdown format:

const chat = new ChatBot(node, { format: "markdown" });

When configured with markdown format, the ChatBot widget will render text using markdown syntax. This allows for more complex text formatting, such as bold, italics, lists, and links, within the chat messages.

These configurations provide developers with the ability to choose the appropriate text format for their application's needs.

Typing Animation​

Detecting New Messages Sent by Users​

Listen for the event when a new message is added to the chat. Use the add-message event listener to detect and log the details of the new message:

chat.on("add-message", ({ id: TID, message: Message }) => 
    console.log("new message", message.content, "added to chat", id)
);

Data Format for Messages in the Chat​

Messages in the chat follow this predefined structure:

type Message = {
    id: TID;
    role: "agent" | "user";
    content: string;
    typing?: number;
}
  • id: A unique identifier for the message.
  • role: Specifies the sender of the message. Possible values are "agent" or "user".
  • content: The actual text content of the message.
  • typing (optional): A numeric value indicating the typing animation state.

Typing Animation States​

The typing property can take the following values:

  • 0: No typing animation (this is the default behavior).
  • 1: Typing animation in streaming mode.
  • -1: Typing animation in finishing mode.

Adding a Message with Typing Animation​

To add a new message with typing animation, use the following command:

chat.exec("add-message", { id: "chat/id", message: { typing: -1 }});

In this example, id: "chat/id" represents the unique identifier for the chat conversation, and message: { typing: -1 } indicates that the message will be added with the finishing typing animation.