Skip to main content

ChatBot Init

Installation​

The ChatBot widget can be installed using npm, via a CDN, or by downloading static files from dhtmlx.com. Follow the respective setup instructions below based on your preferred method.

Using npm​

To install the ChatBot widget with npm, first configure the npm registry to access the private server:

npm config set @dhx:registry https://npm.dhtmlx.com

After configuring the registry, install the ChatBot component:

npm install @dhx/chatbot

To use the ChatBot widget in your project, import the necessary component and initialize it:

import { ChatBot } from "@dhx/chatbot";
const chat = new ChatBot(html_container, {});

Using CDN​

To use the ChatBot widget via CDN, include the following script and link tags in your HTML file:

<link rel="stylesheet" href="https://cdn.dhtmlx.com/chatbot/latest/chatbot.css">
<script src="https://cdn.dhtmlx.com/chatbot/latest/chatbot.js"></script>

The /chatbot/latest/ URL ensures you get the most up-to-date version. Alternatively, specify an exact version (e.g., /chatbot/1.0/) if needed.

Initialize the widget using the following JavaScript code:

const chat = new chatbot.ChatBot(html_container, {});

Using Static Files​

For using static files, download the package from dhtmlx.com, unzip it, and place the dist folder in the public directory of your site or application. Include the script and link tags in your HTML file:

<link rel="stylesheet" href="path/to/your/public/directory/chatbot/dist/chatbot.css">
<script src="path/to/your/public/directory/chatbot/dist/chatbot.js"></script>

Initialize the widget with the following JavaScript code:

const chat = new chatbot.ChatBot(html_container, {});

Ensure the html_container references the HTML element where the ChatBot should be rendered.

Initialization​

Minimal Initialization Code​

To initialize the ChatBot widget, create an instance using the following code snippet:

const chat = new ChatBot(html_container, config);

Parameters​

html_container​

This parameter specifies the container where the ChatBot widget will be rendered. It accepts the following types:

  • HTMLElement: Directly pass an HTML element which will act as the container for the widget.
  • CSS Locator String: Use a CSS selector string to specify the container. Only the first match will be used as the widget container.
    • #some - Selects an element by its ID.
    • .some - Selects an element by its class name.

config​

This optional parameter is a configuration object that allows customizing the widget's behavior.

Writing Agent​

The ChatBot widget supports creating agent-based support channels. It integrates seamlessly with AI bots and offers client-side solutions to handle user messages. The widget focuses on the UI layer without providing a backend solution.

Responding to User Messages: Client-Side Logic​

To respond to user messages on the client side, define an array for storing messages and an agent object with required attributes and response functionality.

Example:

const messages = [];
const agent = {
    id: 1,
    name: "Dummy Agent",
    response: (messages) => {
        const lastMessage = messages[messages.length-1];
        return { content: `your last message contains ${lastMessage.content.length} characters` };
    }
};
const chat = new ChatBot(node, { messages, agent });

Data Format for Agents​

The agent object should conform to the following 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 for the agent's avatar image.
  • response (Optional): A function that handles incoming messages and returns a response message or a promise resolving to a response message.

The response handler is optional and is triggered when the agent receives a new message in the chat. The handler returns a response message object or a promise resolving to a response message. The content field in the response message is mandatory and contains the text of the response.

Data Format for Messages​

Messages exchanged in the chat must adhere to the following type:

type Message = {
    id: TID;
    role: "agent" | "user";
    content: string;
    typing?: number;
};
  • id: Unique identifier for the message.
  • role: Specifies the sender of the message, either "agent" or "user".
  • content: The text content of the message.
  • typing (Optional): Controls the typing animation. Possible values:
    • 0: No typing animation (default).
    • 1: Typing animation in streaming mode.
    • -1: Typing animation finishing.

Responding to User Messages: Server-Side Logic​

To handle user messages using server-side logic, initially load the messages and then define the agent object to fetch responses from the backend.

Example:

let messages = [];

// Load initial data
fetch("/messages")
    .then(response => response.json())
    .then(data => messages = data);

const agent = {
    id: 1,
    name: "Dummy Agent",
    response: (messages) => {
        const lastMessage = messages[messages.length-1];
        // Fetch response from backend
        return fetch(`/response?ask=${lastMessage.content}`)
            .then(response => response.json())
            .then(data => {
                return data;
            });
    }
};

const chat = new ChatBot(node, { messages, agent });

Data Format for Agents and Messages (Server-Side)​

The data format definitions for agents and messages remain consistent with the client-side implementation.

Refer to the sections "Data Format for Agents" and "Data Format for Messages" for the detailed type descriptions.

What next​