Web Chat Overview

This article introduces Web Chat interactive features and interface customization, helping you create a Web Chat service that matches your brand identity

1. What is WebChat?

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 three embedding methods:

1. Bottom-Right Corner Widget

• 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

• Provides a complete conversation experience

• Suitable for complex consultation and service workflows

• Customizable design to meet enterprise needs

3. MaiGPT Window Mode Embed

• A full ChatGPT-style conversation interface (conversation history list on the left + main conversation area on the right) that can be embedded directly into a page as the primary UI

• Can be permanently displayed in a specified container, or opened full-screen by clicking a floating button in the bottom-right corner

• Ideal for AI portal sites, internal knowledge portals, or as the primary conversation interface for a product

MaiGPT window mode can be selected in the "Embed" window of the chat platform settings. For complete setup steps, see MaiGPT Window Mode Embed.

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

2. Build a Brand-Styled Web Chat Service

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

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

3. Message Customization

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

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

• Set "conversation starter questions" 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:

Stop a Response While It Is Being Generated

If you notice an error in your question after sending it, you do not need to wait for the AI assistant to finish the entire response. While the response is being generated, the send button to the right of the input field changes to a square Stop button. Click it to stop the current response, then enter and send your corrected question.

For example, suppose a customer service representative asks the AI assistant to plan an annual product launch but realizes after sending the request that they forgot to specify the event budget. They can click Stop while the AI assistant is generating the response, then add the budget and number of attendees and ask again. This avoids waiting for content that does not meet their needs to finish generating.

Stop the Current Response

1

1. Find the Stop Button

After sending a question, wait for the AI assistant to start generating a response. A square Stop button appears to the right of the input field.

Click the Stop button to the right of the input field while a response is being generated

2

2. Stop and Ask Again

Click Stop. Once the "Typing a response for you" message disappears, enter the corrected question in the input field and send it again.

Stopping only interrupts the response currently being generated. It does not delete the question you sent or any previous conversation history.

4. Diverse Q&A Content

1. Multi-Language Support

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: Web Chat Chat Settings.

2. Use the Web Chat initialization script (JavaScript) to specify the AI assistant's reply language. See: Technical Manual - Web Chat Initialization.

For the list of supported languages, see: Multi-Language Support: Supported Language List

2. Multimodal Q&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

You can disable file uploads for users, restricting conversations to text only to ensure conversation security.

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

The AI assistant replies in Markdown format, organizing response content in a well-structured manner.

5. Conversation Memory and Sharing

1. Conversation History Memory

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

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

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.

6. Choose Whether to Display Tool Usage and Citation Lists

1. Display Tool Usage List

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

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

7. Conversation Access Control - A Secure and Controllable Conversation Environment

1. Login Configuration

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

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:

8. Data Collection (Pre-chat Form)

After data collection is enabled, visitors see a form before starting a conversation and must complete it to continue. Their responses are saved to the visitor's contact, so customer service agents can view them directly on the conversation page. This is useful when you need to identify visitors in advance. For example, distributor support can collect a company name and business registration number, while event inquiries can collect a name and email address.

1. Configure the Data Collection Form

Path: Customer Service → Conversation Platforms → select the Web Chat conversation platform → Data Collection tab.

Data Collection tab: configure the toggle, title, and fields on the left; the Live Preview on the right updates the form's appearance in real time

1

Enable the Form

Turn on Enable Pre-chat Form. When it is disabled, visitors enter the conversation directly, following the original flow.

2

Set the Title and Subtitle (Optional)

• Form title: Appears at the top of the form. If left blank, the system uses the default text "A few questions before we start."

• Form subtitle: Descriptive text for the form. Use {name} to insert the conversation platform name. If left blank, the default text is "Leave your information so {name} can provide more personalized service."

Both fields support multiple languages. Switch language tabs to enter each translation separately.

3

Add Fields

Click Add Field. You can configure the following options for each field:

Setting	Description
Field type	Text, Email, Phone, or Dropdown
Field label	The field name visitors see; enter a separate label for each language
Placeholder	Gray hint text displayed inside the field
Required	When selected, visitors cannot submit the form without completing the field
Contact field mapping	Determines where the data is stored in the contact: Name (Contact.name), Email (Contact.email), Phone (Contact.phoneNumber), or Custom Field (Metadata)

Dropdown fields also have an Options list. Select Allow custom "Other" input to let visitors enter their own response after selecting "Other."

Configure each field's type, localized label, placeholder, Contact field mapping, and required status

Drag fields to reorder them. A form can contain up to 10 fields. The preview area on the right updates the form's appearance in real time. Switch the Preview Language to check each language version.

4

Save

After confirming that the preview is correct, save the form. The changes take effect immediately in Web Chat.

Contact field mapping restrictions

• Name can only map to a Text field, Email can only map to an Email field, and Phone can only map to a Phone field. Incompatible field types are disabled with an explanatory message.

• Name, Email, and Phone can each be mapped by only one form field. For all other fields, such as business registration number or company name, select Custom Field (Metadata).

2. Visitor Form Flow

When visitors open Web Chat, they first see the form with its title, subtitle, configured fields, and a language selector in the upper-right corner. After completing the form, they click Start Conversation to enter the conversation.

Visitors see the form when they open Web Chat

Click Start Conversation after completing the form

• If a required field is empty or an email address or phone number has an invalid format, an error appears below the field and the form cannot be submitted.

• After completing the form once in a browser, the visitor will not be asked to complete it again when opening the same Web Chat.

• To correct their information, visitors can open the ⋮ menu in the upper-right corner of Web Chat and click Refill Information. The form appears again.

Refill Information in the upper-right ⋮ menu

3. Use with Login: Associate Data with a Login Account

If both the login feature and data collection are enabled for the same Web Chat, the flow is: Log in → Complete form → Start conversation. The information entered by a user is associated with their login account rather than their browser.

Situation	Web Chat behavior
The account is being used for the first time and has not completed the form	The form appears after login. Submitting it creates a contact associated with the account.
The same account logs in on another device or browser	The form does not appear again; the conversation starts directly with the account's existing data.
The device previously submitted the form without logging in, but the account has no data	A "Is this information yours?" confirmation screen appears (see below).
The account already has data, and the device has separate data submitted while logged out	The account data takes precedence. The system does not ask for confirmation or merge the records.
A logged-in user clicks Refill Information	The existing contact associated with the account is updated; no additional contact is created.

Confirmation screen: Is this information yours?

If someone previously completed the form on the device without logging in and the account currently logging in does not have any data, the form does not appear immediately after login. Instead, a confirmation screen first displays the information previously entered on the device, partially masked, and provides two buttons:

• Yes, this is mine: Associates that information with the current account. The same account will not need to complete the form again when logging in on any device.

• No: Does not merge the records. The original information remains unchanged, and the form then appears for the user to complete.

• Web Chats without the login feature are unaffected and continue to use the browser to determine whether the form has already been completed.

• The system does not automatically populate the form from account data. The first time an account is used, the user must complete the form even if their information already exists in the admin console.

After the conversation begins, both the AI assistant and customer service agents in the admin console see the same contact associated with the account:

4. View Collected Data in the Admin Console

View in a conversation: Go to Customer Service → All Conversations → open a conversation. The Contact Information section on the right lists each response collected by the form. Fields mapped to Email and Phone appear as "Email" and "Phone Number," while custom fields use the field labels you configured.

The Contact Information section on the right side of the conversation page lists each response collected by the form

The Contact column in the contact list displays the Contact's name. If the form's name field is mapped to Custom Field (Metadata) instead of Name (Contact.name), logged-out visitors appear as Anonymous, and their names are available only in custom attributes. To display visitor names directly in the list, map the name field to Name (Contact.name).

View on the Contacts page: Go to Customer Service → Contacts → open a contact. The Basic Information tab displays the name and phone number, while the Custom Attributes tab displays the other form fields.

Search the contact list by name, email address, or phone number

The Custom Attributes tab lists the value of every form field

Information entered by a logged-in user is associated with their account rather than an unclaimed anonymous contact. The contact name depends on the form configuration: if the name field is mapped to Name (Contact.name), the name entered in the form is displayed; if the form has no name field, the login account name is displayed.

How Do I Handle a Connection Failure?

For example, a website administrator may receive a report from a visitor that Web Chat displays a connection error when opened. The visitor should first wait for the system to retry automatically. If the error screen remains, they should capture the entire screen—including the failed stage, error category, and time of occurrence—and send it to the administrator so the issue can be diagnosed more quickly.

If the network connection is interrupted while Web Chat is loading the AI assistant configuration, it retries automatically and remains on the loading screen during this period. If it still cannot connect after retrying, the error screen displays:

• The loading stage that failed

• The error category, together with the HTTP status code when available

• The local time when the error occurred

After automatic retries fail, the screen lists the failed stage, error category, and time of occurrence

If the system has received an HTTP error status code, the server has already responded. In this case, Web Chat does not retry automatically and displays the diagnostic error screen immediately.

First confirm that the device can access the internet, then click Retry on the error screen. If the issue persists, preserve all diagnostic information in the screenshot and ensure that no conversation content or personal data is visible.