Web Chat Overview
This article introduces Web Chat interaction features and interface customization to help you build a Web Chat service that matches your corporate branding
1. What Is WebChat?
You can embed an AI assistant created in MaiAgent into your website to provide real-time customer support or other conversations. Web Chat also features a responsive design that adapts seamlessly to desktops, tablets, and phones.
MaiAgent currently provides the following three embedding options:
1. Embed in the Bottom-Right Corner
Embed it into your official website as a built-in intelligent assistant
Let users browse without interruption, with help available whenever needed
Suitable for general customer support and consultation services
2. Full-Screen Embedding
Provide a complete conversation experience
Suitable for complex consultations and service workflows
Customize the design to meet business needs
3. MaiGPT Window Mode Embedding
A complete ChatGPT-style conversation interface (conversation history on the left + main conversation area on the right) that can be embedded directly into a page as its primary UI
Keep it visible in a specified container, or expand it to full screen when users click a floating button in the bottom-right corner
Suitable as the main conversation interface for an AI portal, an internal knowledge portal, or a product
This design offers:
Immediate responses: Visitors receive professional answers without waiting, improving the user experience
Convenience: The bottom-right floating widget keeps browsing uninterrupted and is available whenever needed
Cost efficiency: AI assistants provide 24/7 service, significantly reducing staffing costs
A professional image: Showcase your company's technical capabilities and service quality
2. Build a Web Chat Service with Your Corporate Branding
MaiAgent provides customization features for logos, avatars, conversation theme colors, and more to help you build a Web Chat service that matches your corporate branding
You can:
Choose the assistant's display name
Upload your corporate logo
Choose the AI assistant's avatar
Choose the Web Chat theme color
Choose the message background color for AI assistant replies
Use these features to create your own Web Chat appearance:
This lets you build a Web Chat service that matches your corporate style and color requirements
Web Chat displays the platform's brand logo below the conversation input area. The login, registration, and loading screens also display brand images with consistent proportions, without stretching or distortion.
Dark Mode Improvements
MaiAgent's Web Chat dark mode has been comprehensively improved to provide a more comfortable viewing experience:
Dynamic color adjustments
Automatically adjust theme color brightness to keep colors clear on dark backgrounds
Intelligently adjust text contrast for optimal readability
Improve icon and button colors to make them stand out in dark mode
Contrast improvements
Carefully designed message bubble background colors help prevent visual fatigue
High-contrast colors for links and important information make them easy to identify
Improved input field and button border colors enhance usability
Seamless switching
Users can switch between light and dark modes at any time
Conversation content and interaction state are preserved when switching
The system remembers users' theme preferences
Dark mode is especially suitable for:
Nighttime use or low-light environments
Long conversations, to reduce eye strain
Dark visual styles that match corporate branding
3. Message Customization
When users first enter your Web Chat service, you can customize your AI assistant's opening message for scenarios such as the following.
1. Customize the Opening Message
Branded greetings
Set a message such as “Welcome to our website! I'm your dedicated customer support assistant” to convey your company's professionalism and friendly service
Guided introductions
Set a message such as “I can help you find product information, answer usage questions, and handle orders” to clearly explain the services available and build users' confidence in your service capabilities
2. Guided Starter Questions
Set “Conversation Starter Questions” as quick options
Users can click common questions directly without typing
Example questions:
“How do I view the items I've ordered?”
“How do I place an order?”
“Member points rules”
“Business hours”
Users can click a starter question to begin a conversation and get answers faster:
Stop a Response Being Generated
If you notice an error in your question after submitting it, you do not need to wait for the AI assistant to finish its entire response. While a response is being generated, the send button on the right of the input field becomes a square Stop button. Click it to stop the current response, then enter your corrected question.
For example, a customer support representative asks the AI assistant to plan an annual product launch event, then realizes they forgot to specify the budget. They can click Stop while the AI assistant is generating its response, then ask again with the budget and attendee count, avoiding a wait for content that does not meet their needs.
Stop a Response
4. Diverse Question-and-Answer Content
1. Multilingual Support
Reply in the user's language to remove communication barriers.
Automatic detection: Choose the assistant's response language based on the language of the user's input
Manual switching:
Select a language in the Web Chat interface. See Multilingual Support: Web Chat Settings.
Specify the AI assistant's response language in the Web Chat initialization script (javascript). See Technical Manual—Web Chat Initialization.
2. Multimodal Questions and Answers
In addition to text-based questions and answers, AI assistants can support uploads of various file types:
Spreadsheets: .xls, .xlsx, .csv, .ods
Word processing documents: .doc, .docx, .odt, .pdf, .md, .txt
Presentations: .ppt, .pptx, .odp
Web documents: .html, .htm
Data formats: .json, .jsonl
Audio files: .wav, .mp3, .m4a, .aac
Video files: .mp4
Image Content Processing
Image recognition and analysis
Uploaded image analysis: Users can upload product images for AI to recognize automatically and provide related information
Screenshot processing: Support screenshot analysis to help resolve usage issues
Image descriptions: Automatically generate descriptions of image content and related recommendations
Image replies
Product images: Include actual product images in replies
Visual instructions: Provide step-by-step screenshots
Examples:
A user asks where to configure a MaiAgent assistant, and the assistant replies with an image of the settings screen
A user sends a screenshot to confirm whether the path is correct, and the assistant interprets it correctly before replying
Document Processing Capabilities
Supported document formats
PDF documents: Automatically parse PDF content and answer related questions
Word documents: Process .doc/.docx documents
Excel spreadsheets: Analyze spreadsheet data and provide insights
PowerPoint presentations: Extract presentation content and answer questions
Document interaction features
Document queries: Answer specific questions based on uploaded documents
Data analysis: Automatically analyze tabular data and provide statistics in tables
Document summaries: Generate summaries of key content in long documents
Example 1: Ask the AI assistant to present information in a table and provide links to reference materials
Example 2: Ask the assistant to analyze sales content and provide a tabular analysis
Example 3: Upload a docx file and ask the assistant to help analyze issues with CV writing
AI assistants use Markdown for all replies to organize response content clearly.
5. Conversation Memory and Sharing
1. Conversation History Memory
To provide a continuous service experience, WebChat automatically remembers users' conversation history so each conversation can build on previous ones.
What is remembered
Conversation content: Complete question-and-answer records, including text, images, documents, and more
Service status: Unfinished queries and pending issues
Users can view past conversation records in the conversation list on the left of Web Chat, or start a new conversation
Conversation memory can be used for:
Follow-up consultations: A user asks “What was the tent model you recommended last time?” and AI immediately recalls it and replies
Progress tracking: A user says “Continue my previous order inquiry,” and AI automatically retrieves the relevant information
Personalized service: Provide more accurate recommendations and suggestions based on past conversations
2. Conversation Sharing
If you want to share a conversation with friends or colleagues after consulting an AI assistant, or your internal team needs to collaborate on customer issues, use MaiAgent to generate a conversation sharing link:
Click Share in the upper-right corner of the chat window, then copy the public link in the pop-up and send it to others.
Shared content
Complete conversation records: Include all text, images, documents, and other content
Conversation summaries: Automatically generate summaries of key points
Related resources: Product links, documents, and other resources mentioned in the conversation
Conversation sharing can be used for:
Customer sharing: “This camping gear recommendation is great. I'll share it with my hiking group”
Internal collaboration: Customer support representatives share complex issues with the technical support team
Training: Share typical conversation examples as employee training materials
3. Conversation Timeout Management
To ensure conversation quality and system performance, Web Chat includes intelligent conversation timeout management:
Intelligent filtering
Automatically filter greetings: The system identifies and filters opening greetings so they are excluded from timeout calculations
Correctly reset message counts: The message counter resets correctly when a conversation restarts
Improved timeout detection: Only substantive conversation content counts toward timeouts, providing more accurate conversation management
Conversation continuity
Ensure users do not encounter unexpected timeouts during normal conversations
Allow conversations to continue after long pauses or time spent thinking
The system intelligently determines whether a conversation is still active
How it works
Start a conversation: A user sends a greeting (such as “Hello”), which the system excludes from timeout calculations
Enter the conversation: The user begins asking substantive questions, and the timeout timer starts
Pause the conversation: If the user temporarily leaves, the system preserves the conversation state
Resume: The user returns to continue the conversation, and the message count updates correctly
This improvement makes conversations smoother and more natural, so users do not need to worry about interruptions caused by spending too long thinking.
6. Choose Whether to Display Tools Used and Cited Documents
1. Display the Tools Used
You can choose whether users can see the list of tools the AI assistant uses during reasoning. If enabled, the following screen appears while the AI assistant generates a response:
Use this list to check whether the AI assistant is using the tools correctly.
2. Display Cited Documents
Each AI answer automatically generates a list of cited documents, clearly identifying information sources to improve credibility and traceability.
Display settings
Businesses can choose whether users can see the list of cited tools and reference document names. If enabled, the following list appears at the bottom of the AI assistant's reply. Click “Citation Node” to view the referenced document excerpt:
Choose whether to disclose citation information according to the use case:
Public customer support: Display all citations to build trust
Internal support: Hide sensitive documents to protect confidential information
Educational institutions: Display learning resources for students to consult
7. Conversation Access Control — A Secure, Controlled Conversation Environment
1. Login Settings
Require login
To keep conversation content secure and controlled, businesses can enable login and require users to sign in before using AI assistant services. Once configured, visitors who click WebChat are first taken to a login page. Only users who successfully log in can start a conversation with the AI assistant
Security benefits
Authentication: Ensure each conversation user has an identifiable identity
Access control: Provide services according to the user's identity
Conversation tracking: Fully record each user's conversation history
Data protection: Prevent unauthorized access to sensitive information
2. Three Login Methods
AD (Active Directory) login
Use case: Internal employees, integrating with an existing AD system
Features: Single sign-on (SSO) without additional account management
Setup: Configure AD server connection details and synchronization rules
Practical application: Employees sign in directly with their corporate accounts and automatically receive the corresponding permissions
Keycloak login
Use case: Businesses that need complex identity management, with support for multiple identity providers
Features: Support standard protocols including OAuth2, SAML, and OpenID Connect
Setup: Configure the Keycloak server, user pool, and identity providers
Practical application: Integrate user identities across multiple systems and manage permissions centrally
Extension: Let the AI assistant use the visitor's Keycloak login identity when calling MCP/API tools. See Use the Keycloak Login Identity for Tool Calls
MaiAgent login
Use case: Simple user management requirements and fast deployment
Features: Built-in user management with straightforward, intuitive operation
Setup: Create user accounts and permissions in MaiAgent
Practical application: Create a dedicated login system for a specific group of users
Once enabled, the following screen requires users to log in before starting a conversation:
3. Use the Keycloak Login Identity for Tool Calls
After a visitor logs in to Web Chat through Keycloak, the AI assistant can automatically include the visitor's own Keycloak login credential when calling MCP tools or API tools on their behalf. When your backend receives the request, it can use the same Keycloak system to verify who the visitor is and return only the data they are allowed to view. You do not need to configure separate accounts for every tool or ask visitors to log in again.
This feature is off by default. When it is off, all tool calls work exactly as before.
Use Case
A company's internal service portal uses Keycloak to manage employee accounts and Web Chat as an employee assistant. An IT administrator enables this feature on the conversation platform and adds the host of the company's leave management system to the allowlist. After logging in to Web Chat, an employee asks “How many days of annual leave do I have left?” The AI assistant calls the leave system's API tool with that employee's own login credential in the request. The leave system identifies the employee from the credential and returns only their attendance and leave data. When another employee asks, they receive their own data.
Prerequisites
Your organization has completed Keycloak integration. Visitors must be members of your organization. When they first log in through your organization's configured Keycloak, the system automatically creates an account and adds them to the organization (see Third-Party Login: First Login).
In the conversation platform's “Login Settings,” “Enable Login” is on, and “Login Source” is set to Keycloak.
The MCP/API tools that will receive credentials have been created and assigned to the AI assistant used by this conversation platform. The receiving system can validate credentials issued by your Keycloak Realm.
Setup Steps
Settings location: In the left menu, select “Customer Conversations > Conversation Platforms,” choose a website-type conversation platform, and open the “Login Settings” tab. This section appears after you select Keycloak as the login source.
Turn on “Use the Keycloak Login Identity for Tool Calls.”
Read the red warning below the switch, “The visitor's own login credential will be forwarded to the following hosts,” and confirm that you understand where credentials will be sent.
In “Tool Hosts Allowed to Receive Credentials,” enter the tool hosts that should receive credentials, one per line (or separated by commas):
Enter only the hostname, without
https://, a port number, or a path, such asmcp.example.com.*.example.commatchesexample.comitself and all its subdomains. A hostname without*.only matches that exact host.Hostnames are matched against the tool's “MCP Server URL” or “API URL.”
Save the settings.
When the switch is on, the list must contain at least one host. If the list is empty or contains an invalid hostname, the screen displays “Enter at least one tool host allowed to receive credentials when enabled” or “The following hostnames are invalid,” and the settings are not submitted.
After enabling this feature, visitors must log in again. The platform saves Keycloak credentials only when a visitor logs in, and only if a conversation platform has this feature enabled. Ask visitors who were already logged in before it was enabled to log out and log back in. Subsequent tool calls will then include their credentials.
What the Receiving System Gets
When the AI assistant calls an MCP/API tool on a listed host, the request includes an additional HTTP header:
This is the standard access token issued to the visitor by your Keycloak Realm. The engineer handling the integration can identify the user through standard Keycloak token validation (verifying the signature, expiration, and Realm). When the credential expires, the platform first renews it with the same Keycloak using the visitor's login session, then sends the request. The tool does not need to handle renewal.
When Credentials Are Included and When They Are Not
The visitor has logged in with Keycloak, is still logged in, and the tool host is on the list
Includes the visitor's own credentials
The tool host is not on the list
Calls the tool as usual, without credentials
The tool already has Authorization configured (OAuth, API tool headers, contact MCP credentials, etc.)
Does not overwrite it; retains the tool's original authentication method
The visitor has logged out or is not a member of this organization
Does not include credentials
The visitor enters the conversation through Source ID access without login
Does not include credentials; identity is based on the organization member bound when the conversation was created, rather than the Source ID supplied by the embedding site
The toggle is off
Behaves as it did before this feature was enabled
The visitor's complete login credentials are forwarded. A system that receives them can access other services protected by the same Keycloak instance as that visitor. Only list hosts you trust that actually need to identify users, and avoid overly broad wildcards.
8. Data Collection (Pre-chat Form)
When data collection is enabled, visitors see a form before starting a conversation and must complete it to enter the chat. Their entries are saved to the visitor's contact, so support agents can see them directly on the conversation page. This is useful when you need to know who the visitor is first, such as collecting a company name and business registration number for dealer support, or a name and Email for event inquiries.
1. Configure the Data Collection Form
Path: Customer Conversations → Conversation Channels → Select the Web Chat channel → Data Collection tab.
Set the Title and Subtitle (Optional)
Form Title: Appears at the top of the form. If left blank, the default text is “A few questions before we start chatting”.
Form Subtitle: Explanatory text for the form. Use
{name}to insert the conversation channel name. If left blank, the default text is “Leave your details so {name} can provide more personalized service”.
Both support multiple languages. Switch language tabs to enter each version separately.
Add Fields
Click Add Field. Each field has these settings:
Field Type
Four types: text, Email, phone, and dropdown
Field Label
The field name visitors see; can be set separately for each language
Placeholder
Gray hint text inside the field
Required
When selected, visitors cannot submit without completing the field
Mapped Contact Field
Determines where the data is saved 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 Input for “Other” to let visitors enter their own text after selecting “Other”.
Drag fields to reorder them. A form can contain up to 10 fields. The preview on the right updates immediately; switch the Preview Language to check each language version.
2. Visitor Form Flow
When visitors open Web Chat, they first see the form: its title, subtitle, configured fields, and the language switcher in the upper-right corner. After completing it, they click Start Conversation to enter the chat.
If a required field is empty or an Email or phone number has an invalid format, an error appears below the field and submission is blocked.
Once a visitor completes the form in a browser, they will not be asked to complete it again when reopening the same Web Chat in that browser.
To correct their information, visitors can select Fill In Your Details Again from the ⋮ menu in the upper-right corner of Web Chat. The form appears again.
3. Use with Login: Map Data to the Login Account
If the same Web Chat has both login and data collection enabled, the flow is: Log in → Complete the form → Start the conversation. The submitted data is linked to the user's login account rather than the browser.
The account is used for the first time and has not completed the form
Shows the form after login; creates a contact linked to the account after submission
The same account logs in on a different device or browser
Skips the form and starts the conversation with the account's existing data
Someone previously completed the form on this device without logging in, and the account itself has no data
Shows an “Is this your information?” confirmation screen (see below)
The account already has data, and this device also has data submitted while logged out
Uses the account's data without asking or merging
A logged-in user clicks Fill In Your Details Again
Updates the account's existing contact without creating another one
Confirmation Screen: Is This Your Information?
If someone previously completed the form on this device without logging in, and the currently logged-in account has no data, the form does not appear immediately after login. Instead, a confirmation screen first shows the previously entered information from this device (partially masked), with two buttons:
Yes, This Is Mine: Links that information to the current account. The same account will not need to complete the form again on any device.
No: Does not merge the data and leaves the original record unchanged, then shows the form for the user to complete once.
After entering the conversation, both the AI assistant and the support console use this contact linked to the account:
4. View Collected Data in the Admin Console
View in a conversation: Customer Conversations → All Conversations → Open a conversation. The Contact Information section on the right lists each item collected by the form. Fields mapped to Email and Phone appear as “Email” and “Phone Number”; custom fields use the labels you configured.
View on the contact page: Customer Conversations → Contacts → Open a contact. The Basic Information tab shows the name and phone number, and the Custom Attributes tab shows other form fields.
Data submitted by logged-in users is linked to their accounts, so the contact is no longer an unassigned anonymous contact. The contact name depends on the form settings: if a name field maps to Name (Contact.name), the name entered in the form is shown; if there is no name field, the login account's name is shown.
What to Do When a Connection Fails
For example, a visitor reports to a website administrator that Web Chat shows a connection error when opened. The visitor first waits for the system to retry automatically. If the error screen remains, they capture the full screen, including the failed stage, error category, and time, and send it to the administrator to help identify the issue faster.
If a network interruption occurs while Web Chat loads the AI assistant settings, it first retries automatically and keeps displaying the loading screen during that time. If the connection still fails after retrying, the error screen shows:
The loading stage that failed
The error category, along with the HTTP status code if available
The local time when the error occurred
If the system has received an HTTP error status code, the server has responded. In this case, it displays the diagnostic error screen immediately without automatically retrying.
Review Earlier Messages While a Reply Is Being Generated
While the AI assistant is still generating a reply, visitors can scroll up to review earlier messages. The reply continues to appear below, but the screen stays where the visitor scrolled instead of being pulled down by new text. Once they move away from the latest content, Back to Latest appears above the input box.
Usage Scenario
A visitor asks the AI assistant to compare several plans at once. Before the answer is finished, she scrolls up to check the first plan's price. The screen stays in place even as more text appears below. After checking, she clicks Back to Latest. The screen returns to her last question so she can continue reading the rest of the comparison.
Steps
Last updated
Was this helpful?