Web Chat initialization

This article will introduce how to initialize MaiAgent's Web Chat service

In MaiAgent, you can initialize Web Chat via an embed script. Parameters and other explanations are as follows:

Initialization instructions

How to obtain the embed script? Please refer to 🌐Connect Inbox: Website

Follow these instructions and the script will automatically include the webChatId parameter

After the embed script loads, the system will automatically register document.body.onload event handler to execute Web Chat initialization; manual registration calls are not required. If you need to control the initialization timing (for example, waiting for other resources to finish loading or delaying rendering), you can use the following methods:

1. Defer loading the script：control embed.min.js loading timing

2. Manually trigger initialization：call document.body.onload() method

This mechanism allows developers to decouple DOM rendering from Web Chat initialization, providing a more flexible integration approach.

Configuration

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'The Web Chat ID obtained from the Admin embed window',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    contactId: '01f46751-c16f-49d5-970e-84e77e10239d',  // Contact ID
    queryMetadata:{
      // QueryMetadata condition constraints
    }
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

MaiAgent Web Chat configuration parameter descriptions

Parameter name	Type	Required	Description
webChatId	String	Yes	The unique identifier for the Web Chat obtained from the Admin dashboard embed window
baseUrl	String	Yes	The base URL for the MaiAgent Web Chat service. The URL to create a Web Chat isPOST https://chat.maiagent.ai/web-chats
primaryColor	String	No	The primary color of the chat window, using HEX color code format, for example #3854d8
allowDrag	Boolean	No	Whether to allow users to drag the chat window position. Set to true or false
contactId	String	No	Contact ID. You can set a contact's queryMetadata in MaiAgent Admin. Please refer to:Contact integration Learn the mechanism for obtaining the Contact ID
queryMetadata	Object	No	Knowledge search scope settings. For details, please refer to:Get started — using JSON format

Language settings

After embedding MaiAgent Web Chat, you can control the chat interface text language and speech language settings via JavaScript.

// Set the interface to Traditional Chinese
globalThis.MaiAgent.locale.set('zh-TW') 

// Set ASR and TTS to use English
globalThis.MaiAgent.speech.set('en') 

1. Web Chat language and speech control

• Web Chat supports multiple languages including Traditional and Simplified Chinese, English, Japanese, Korean, Thai, etc., and will continue to expand in the future

• After embedding you can globally access the globalThis.MaiAgent object and set text or speech languages

• Except for “Traditional Chinese” and “Simplified Chinese”, other languages only require specifying the “language code”

2. Language setting examples

You can set different interface and speech options according to website requirements:

• Text interface: can be set to Traditional Chinese (zh-TW), Simplified Chinese (zh-CN), English (en), etc.

• Speech settings: can set the language used by ASR (automatic speech recognition) and TTS (text-to-speech)

3. Languages currently supported by MaiAgent

Language code	Language
zh-TW	Traditional Chinese
zh-CN	Simplified Chinese
en	English
th	Thai
ms	Malay
vi	Vietnamese
id	Indonesian
fil	Filipino
my	Burmese
km	Khmer
lo	Lao
ja	Japanese
ko	Korean

Notes

• The system will only initialize after confirming via the Contact API that a Contact ID is present.

• You can use Query Metadata so the Web Chat includesknowledge management permissions

To learn more about knowledge management permissions, please refer to 🌐Knowledge Management Permissions (Query Metadata) Overview↗