> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/conversations/web-chat.md).

# Web Chat Overview

## <mark style="color:blue;">1. What is WebChat?</mark> <a href="#what-is-webchat" id="what-is-webchat"></a>

You can embed AI assistants created on MaiAgent into your website to provide real-time customer service or other conversations. Web Chat features a **responsive design that adapts perfectly to desktop, tablet, and mobile devices.**

MaiAgent currently offers the following two embedding methods:

### 1. Bottom-Right Corner Widget <a href="#embed-widget" id="embed-widget"></a>

* Embed into your website as a built-in smart assistant
* Non-intrusive to normal browsing, available whenever needed
* Ideal for general customer service and consultation

### 2. Full-Screen Embed <a href="#embed-fullscreen" id="embed-fullscreen"></a>

* Provides a complete conversation experience
* Suitable for complex consultation and service workflows
* Customizable design to meet enterprise needs

This design delivers:

* **Immediacy**: Visitors get professional answers instantly without waiting, enhancing user experience
* **Convenience**: The floating bottom-right design doesn't interfere with normal browsing, available whenever needed
* **Cost Efficiency**: AI assistant provides 24/7 service, significantly reducing labor costs
* **Professional Image**: Demonstrates the enterprise's technological capabilities and service quality

## <mark style="color:blue;">2. Build a Brand-Styled Web Chat Service</mark> <a href="#branding" id="branding"></a>

MaiAgent offers customization features including custom logos, avatars, and Q\&A theme colors to help you build a brand-styled Web Chat service

You can:

1. Choose the assistant display name
2. Upload your company logo
3. Choose the AI assistant display avatar
4. Select the Web Chat theme color
5. Select the message background color for AI assistant replies

to create your own Web Chat appearance:

This way, you can create a Web Chat service that matches your brand colors and corporate identity

### Dark Mode Optimization <a href="#dark-mode" id="dark-mode"></a>

MaiAgent's Web Chat dark mode has been fully optimized to provide a more comfortable visual experience:

**Dynamic Color Adjustment**

* Automatically adjusts theme color brightness to ensure visibility on dark backgrounds
* Intelligently adjusts text contrast for optimal readability
* Optimizes icon and button colors for better visibility in dark mode

**Contrast Optimization**

* Message bubble background colors are carefully designed to prevent visual fatigue
* Links and important information use high-contrast colors for clear identification
* Input field and button border colors are optimized to enhance the user experience

**Seamless Switching Experience**

* Users can switch between light and dark modes at any time
* Conversation content and operation states are preserved during switching
* The system remembers the user's theme preference

Dark mode is particularly suitable for:

* Nighttime use or low-light environments
* Extended conversations to reduce eye strain
* Enterprise brand designs with dark color schemes

## <mark style="color:blue;">3. Message Customization</mark> <a href="#messages" id="messages"></a>

When entering the Web Chat service for the first time, you can freely configure your AI assistant's opening message based on the following scenarios.

### **1. Greeting Customization** <a href="#greeting" id="greeting"></a>

#### **Branded Greeting**

Set: "Welcome to our website! I'm your dedicated customer service assistant" to showcase your enterprise's professional image and friendly service attitude

#### **Guided Opening**

Set: "I can help you look up product information, answer usage questions, and assist with order processing" to clearly inform users of the available service scope and build trust in the service capabilities

### 2. Guided Starter Questions <a href="#starter-questions" id="starter-questions"></a>

* Set "<mark style="color:blue;">conversation starter questions</mark>" as quick options
* Users can directly click on common questions without typing
* **Example questions**:
  * "How do I check my ordered items?"
  * "How do I place an order?"
  * "Membership points rules"
  * "Business hours"

Users can tap starter questions to begin a conversation, speeding up the Q\&A process:

## <mark style="color:blue;">4. Diverse Q\&A Content</mark> <a href="#multimodal-qa" id="multimodal-qa"></a>

### 1. Multi-Language Support <a href="#multi-language" id="multi-language"></a>

Responds in the user's language, eliminating communication barriers.

* **Auto-detection**: Selects the assistant's reply language based on the user's input language

**Manual switching**:

1. Use the Web Chat interface to select the language. See: [Multi-Language Support](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/conversations/pages/BaXHx76Xacpa5IBNtuzL#id-2.-web-chat-liao-tian-she-ding)[: Web Chat Chat Settings](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/conversations/pages/BaXHx76Xacpa5IBNtuzL#id-2.-web-chat-liao-tian-she-ding).
2. Use the Web Chat initialization script (JavaScript) to specify the AI assistant's reply language. See: [Technical Manual - Web Chat Initialization](https://docs.maiagent.ai/tech/api-integration/web-chat-chu-shi-hua#e5-9b-9bweb-chat-e5-b5-8c-e5-85-a5-e8-88-87-e8-aa-9e-e8-a8-80-e8-a8-a-d-e5-ae-9a).

{% hint style="info" %}
For the list of supported languages, see: [Multi-Language Support](/maiagent-user-guide/maiagent-user-guide-en/build/multi-language-support.md#zhi-yuan-yu-yan-qing-dan)[: Supported Language List](/maiagent-user-guide/maiagent-user-guide-en/build/multi-language-support.md#zhi-yuan-yu-yan-qing-dan)
{% endhint %}

### 2. Multimodal Q\&A <a href="#multimodal" id="multimodal"></a>

In addition to text-based Q\&A, the AI assistant also supports uploading different types of files:

* Spreadsheets: .xls, .xlsx, .csv, .ods
* Word processing documents: .doc, .docx, .odt, .pdf, .md, .txt
* Presentation files: .ppt, .pptx, .odp
* Web files: .html, .htm
* Data formats: .json, .jsonl
* Audio files: .wav, .mp3, .m4a, .aac
* Video files: .mp4

{% hint style="info" %}
You can disable file uploads for users, restricting conversations to text only to ensure conversation security.
{% endhint %}

#### Image Content Processing

**Image Recognition and Analysis**

* **Upload image analysis**: Users can upload product images, and the AI automatically identifies and provides relevant information
* **Screenshot processing**: Supports screenshot analysis to help resolve usage issues
* **Image descriptions**: Automatically generates image content descriptions and related suggestions

**Image Response Feature**

* **Product image display**: Replies include actual product images
* **Operation guide images**: Provides step-by-step operation screenshots

Examples:

1. A user asks where to configure the MaiAgent assistant, and the assistant responds with an image of the settings screen
2. A user sends a screenshot to the assistant to confirm whether the path is correct, and the assistant correctly interprets and responds

#### Document Processing Capabilities

**Supported Document Formats**

* **PDF files**: Automatically parses PDF content and answers related questions
* **Word documents**: Processes .doc/.docx format documents
* **Excel spreadsheets**: Analyzes spreadsheet data and provides insights
* **PowerPoint presentations**: Extracts presentation content and answers questions

**Document Interaction Features**

* **Document content queries**: Answers specific questions based on uploaded documents
* **Data analysis**: Automatically analyzes table data and provides statistical information in table format
* **Document summaries**: Generates key content summaries for long documents

***

Example 1: Ask the AI assistant to present data content in table format and provide reference links

Example 2: Ask the assistant to analyze sales content and provide table analysis

Example 3: Upload a docx file and ask the assistant to help analyze CV writing issues

{% hint style="success" %}
The AI assistant replies in Markdown format, organizing response content in a well-structured manner.
{% endhint %}

## <mark style="color:blue;">5. Conversation Memory and Sharing</mark> <a href="#memory-and-sharing" id="memory-and-sharing"></a>

### **1. Conversation History Memory** <a href="#chat-history" id="chat-history"></a>

To provide a continuous service experience, WebChat automatically remembers users' conversation history, allowing each conversation to build upon previous ones.

**Memory Scope**

* **Conversation content**: Complete Q\&A records, including text, images, documents, etc.
* **Service status**: Incomplete queries, pending issues

Users can view past conversation records in the conversation list on the left side of Web Chat, or start a new conversation

The conversation memory feature can be used for:

* **Continuous consultation**: When a user asks "What tent model did you recommend last time?", the AI can immediately recall and answer
* **Progress tracking**: When a user says "Continue the order inquiry from last time", the AI automatically retrieves the relevant information
* **Personalized service**: Provides more accurate recommendations and suggestions based on conversation history

### **2. Conversation Sharing** <a href="#chat-sharing" id="chat-sharing"></a>

When you want to share a conversation with friends or colleagues after consulting the AI assistant, or when internal teams need to collaborate on customer issues, you can use MaiAgent's service to generate a conversation sharing link:

**Shared Content**

* **Complete conversation record**: Includes all text, images, documents, and other content
* **Conversation summary**: Automatically generated conversation highlights summary
* **Related resources**: Product links, documents, etc. mentioned in the conversation

Conversation record sharing can be used for:

* **Customer sharing**: "This camping gear recommendation is great, share it with the hiking club"
* **Internal collaboration**: Customer service staff share complex issues with the technical support team
* **Training purposes**: Share typical conversation cases as employee training materials

### **3. Conversation Timeout Management** <a href="#chat-timeout" id="chat-timeout"></a>

To ensure conversation quality and system performance, Web Chat features an intelligent conversation timeout management mechanism:

**Intelligent Filtering Mechanism**

* **Automatic greeting filtering**: The system identifies and filters opening greetings, excluding them from conversation timeout calculations
* **Correct message count reset**: When a conversation restarts, the message counter resets correctly
* **Optimized timeout determination**: Timeout calculations only apply to substantive conversation content, providing more accurate conversation management

**Conversation Continuity Assurance**

* Ensures users do not unexpectedly time out during normal conversations
* Conversations can continue after extended periods of thinking or pauses
* The system intelligently determines whether a conversation is still in progress

**How It Works**

1. **Start conversation**: The user sends a greeting (e.g., "Hello"), which the system does not count toward the timeout
2. **Enter conversation**: The user begins asking substantive questions, and the timeout timer starts
3. **Conversation pause**: If the user temporarily leaves, the system maintains the conversation state
4. **Resume**: The user returns to continue the conversation, and the message count updates correctly

This optimization makes the conversation experience smoother and more natural, so users don't need to worry about interruptions due to extended thinking time.

## <mark style="color:blue;">6. Choose Whether to Display Tool Usage and Citation Lists</mark> <a href="#display-tools-and-citations" id="display-tools-and-citations"></a>

### **1. Display Tool Usage List** <a href="#show-tools" id="show-tools"></a>

You can choose whether to let users see the list of tools the AI assistant uses during reasoning. If enabled, the following screen appears when the AI assistant generates a response:

You can use this list to verify whether the AI assistant is using the correct tools.

### **2. Display Citation List** <a href="#show-citations" id="show-citations"></a>

Each AI response automatically generates a citation list, clearly indicating information sources to enhance the credibility and traceability of answers.

**Display Settings**

Enterprises can configure whether to let users see the tool usage list and reference document names. If display is enabled, the following list appears at the bottom of the AI assistant's response. Clicking on a "citation node" reveals the referenced document excerpt:

Depending on different usage scenarios, you can choose whether to display citation information:

* **Public customer service**: Display all citation information to build trust
* **Internal support**: Hide sensitive documents to protect confidential information
* **Educational institutions**: Display learning resources for convenient student reference

## <mark style="color:blue;">7. Conversation Access Control - A Secure and Controllable Conversation Environment</mark> <a href="#access-control" id="access-control"></a>

### 1. Login Configuration <a href="#login-config" id="login-config"></a>

**Mandatory Login Mechanism**

To ensure the security and controllability of conversation content, enterprises can enable the login feature, requiring users to log in before using the AI assistant service. Once configured, visitors clicking on WebChat will first be directed to a login page, and only successfully authenticated users can begin conversations with the AI assistant

**Security Advantages**

* **Identity verification**: Ensures every conversation user has a verified identity
* **Access control**: Provides corresponding service content based on user identity
* **Conversation tracking**: Maintains complete conversation history records for each user
* **Data protection**: Prevents unauthorized users from accessing sensitive information

### 2. Three Login Methods <a href="#login-methods" id="login-methods"></a>

**AD (Active Directory) Login**

* **Use case**: For internal employees, integrated with existing AD systems
* **Features**: Single Sign-On (SSO), no additional account management needed
* **Setup**: Configure AD server connection information and synchronization rules
* **Practical application**: Employees log in directly with company accounts and automatically receive corresponding permissions

**Keycloak Login**

* **Use case**: For enterprises requiring complex identity management, supporting multiple identity providers
* **Features**: Supports standard protocols such as OAuth2, SAML, and OpenID Connect
* **Setup**: Configure Keycloak server, user pools, and identity providers
* **Practical application**: Integrate user identities across multiple systems with unified permission management

**MaiAgent Login**

* **Use case**: For simple user management needs with quick deployment
* **Features**: Built-in user management system, simple and intuitive operation
* **Setup**: Create user accounts and permissions on the MaiAgent platform
* **Practical application**: Create a dedicated login system for specific user groups

Once enabled, the following screen will appear before starting a conversation, requiring login:


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/conversations/web-chat.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.