> 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/en/conversations/web-chat.md). # 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 {% hint style="info" %} MaiGPT window mode can be selected in the "Embed" window of the chat platform settings. For complete setup steps, see [MaiGPT Window Mode Embed](/maiagent-user-guide/en/conversations/web-chat/maigpt-embed.md). {% endhint %} 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 Web Chat displays the platform branding below the conversation input area. The login, registration, and loading screens also display the brand image at a consistent aspect ratio without compressing, stretching, or distorting it.
Powered by and the MaiAgent brand logo displayed below the Web Chat input area

The brand logo at the bottom of Web Chat remains clear and preserves its aspect ratio

### 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 {% stepper %} {% step %} ### 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.
A square Stop button appears to the right of the input field while Web Chat is generating a response

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

{% endstep %} {% step %} ### 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. {% endstep %} {% endstepper %} {% hint style="info" %} Stopping only interrupts the response currently being generated. It does not delete the question you sent or any previous conversation history. {% endhint %} ## 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](https://docs.maiagent.ai/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/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/en/build/multi-language-support.md#zhi-yuan-yu-yan-qing-dan)[: Supported Language List](/maiagent-user-guide/en/build/multi-language-support.md#zhi-yuan-yu-yan-qing-dan) {% endhint %} ### 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 {% 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 %} ## 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](/maiagent-user-guide/en/org/contact.md), 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

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

{% stepper %} {% step %} ### Enable the Form Turn on Enable Pre-chat Form. When it is disabled, visitors enter the conversation directly, following the original flow. {% endstep %} {% step %} ### 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. {% endstep %} {% step %} ### 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."
Field editor

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. {% endstep %} {% step %} ### Save After confirming that the preview is correct, save the form. The changes take effect immediately in Web Chat. {% endstep %} {% endstepper %} {% hint style="info" %} **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). {% endhint %} ### 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.
Form displayed to visitors

Visitors see the form when they open Web Chat

Completed form

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

Refill Information in the upper-right ⋮ menu

### 3. Use with Login: Associate Data with a Login Account If the same Web Chat has both the [login feature](#login-config) and data collection enabled, the flow is: **Log in → Fill out the form → Start the conversation**. The information entered by the user is associated with their login account rather than the browser.
Login Settings tab

On the "Login Settings" tab, enable "Enable Login" and select a login source; these settings are independent of the "Data Collection" tab

Login screen

① When Web Chat opens, the login screen appears first

Form after login

② The data collection form appears only after login

| Situation | Web Chat behavior | | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | The account is being used for the first time and has not completed the form | The form appears after login. Once submitted, a contact associated with the account is created. | | The same account logs in on a different device or browser | The form does not appear again. The conversation starts immediately using the account's existing information. | | The form was previously completed on this device while logged out, but the account has no information | An "Is this information yours?" confirmation screen appears (see below). | | The account already has information, and this device has separate information entered while logged out | The account information 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; a new contact is not created. | **Confirmation screen: Is this information yours?** If someone previously completed the form on this device without logging in and the account currently logging in has no information, the form does not appear immediately after login. Instead, a confirmation screen appears first. It displays the information previously entered on this device, with some details masked, and provides two buttons: * Yes, this is mine: Associates that information with the current account. The user will not need to complete the form again when logging in to the same account on any device. * No: Does not merge the records. The original information remains unchanged, and the form then appears for the user to complete.
Is this information yours? confirmation screen

The confirmation screen masks some details, showing only enough information for users to determine whether they submitted it

{% hint style="info" %} * Web Chats without the login feature enabled 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 with account information. The first time an account is used, the user is still asked to complete the form even if their information already exists in the admin console. {% endhint %} After the conversation starts, both the AI assistant and customer service staff see the contact associated with the account:
Conversation after login

The AI assistant addresses the user by the name entered in the form

Conversation page in the admin console

The conversation page in the admin console displays the contact and the business registration number collected through the form

### 4. View Collected Information 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 item collected through the form. Fields mapped to email and phone are displayed as "Email" and "Phone Number," while custom fields use the field labels you configured.
Contact Information section on the right side of the conversation page

The "Contact Information" section on the right side of the conversation page lists each item collected through the form

{% hint style="info" %} The "Contact" column in the contact list displays the contact's name. If the form's name field is mapped to "Custom Field (Metadata)" rather than "Name (Contact.name)," contacts for visitors who are not logged in are displayed as "Anonymous," and the name appears only in the custom attributes. To display visitor names directly in the list, map the name field to "Name (Contact.name)." {% endhint %} **View on the contact 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.
Contact list

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

Custom Attributes tab

The "Custom Attributes" tab lists the value of each form field

Information entered by a logged-in user is associated with their account, so the contact is no longer 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 does not have a name field, the login account's name is displayed. ## What Should I Do If the Connection Fails? 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 settings, it automatically retries first. The loading screen remains visible during this time. If it still cannot connect after retrying, the error screen displays: * The loading stage that failed * The error category, along with the HTTP status code when available * The local time when the error occurred
Web Chat diagnostic for a network connection failure while loading AI assistant settings

If 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, it does not retry automatically and displays the diagnostic error screen immediately. {% hint style="info" %} First, confirm that the device can access the internet, then click Retry on the error screen. If the problem persists, include all diagnostic information in the screenshot and make sure that no conversation content or personal information is visible. {% endhint %} ## Review Earlier Messages While a Response Is Being Generated While the AI assistant is still generating a response, visitors can scroll up to review earlier messages. The response continues to be generated below, but the view remains at the visitor's current scroll position instead of being pulled down by newly generated text. As soon as the visitor leaves the latest position, a Back to Latest button appears above the input box. ### Scenario A visitor asks the AI assistant to compare several options at once. Before the response is complete, she wants to check the price of the first option, so she scrolls up. The view stays where it is and does not jump as more text appears below. After checking the price, she clicks Back to Latest. The view returns to the position of her latest question so she can continue reading the rest of the comparison. ### How to Use It {% stepper %} {% step %} ### 1. Scroll Up While the AI assistant is generating a response, scroll up using the mouse wheel, a touch gesture, or by dragging the scroll bar. {% endstep %} {% step %} ### 2. Read at Your Current Position The view remains at the position you scrolled to. Newly generated content does not change your current position.
Scroll up while Web Chat is generating a response; Back to Latest appears above the input box

The response is still being generated (the square Stop button appears on the right side of the input box). After you scroll up, "Back to Latest" appears above the input box

{% endstep %} {% step %} ### 3. Return to the Latest Message Click Back to Latest. The view returns to the position of the latest question and resumes automatically following new content. {% endstep %} {% endstepper %} --- # 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/en/conversations/web-chat.md?ask=&goal= ``` `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.