Web Chat 初始化

本篇將介紹如何初始化 MaiAgent 的 Web Chat 服務

在 MaiAgent 中可以透過嵌入腳本進行 Web Chat 的初始化，參數及其他說明如下：

初始化說明

如何獲取嵌入腳本？請參考 🌐串接對話平台：網站

依此說明操作，腳本將會自動帶入 webChatId 參數

嵌入腳本載入後系統會自動註冊 document.body.onload 事件處理器來執行 Web Chat 初始化，不需要手動呼叫註冊。若需要控制初始化時機（例如等待其他資源載入完成或延遲渲染），可採用以下方式：

1. 延遲載入腳本：控制 embed.min.js 的載入時機

2. 手動觸發初始化：在適當時機調用 document.body.onload() 方法

此機制允許開發者將 DOM 渲染與 Web Chat 初始化解耦，提供更靈活的整合方式。

配置方式

<script>
  window.maiagentChatbotConfig = {
    webChatId: '從 Admin 嵌入視窗中獲得的 Web Chat ID',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    contactId: '01f46751-c16f-49d5-970e-84e77e10239d',  // 聯絡人ID
    queryMetadata:{
      // QueryMetadata 條件限制
    }
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

MaiAgent Web Chat 配置參數說明

參數名稱	類型	必填	說明
webChatId	String	是	從 Admin 後台嵌入視窗中獲得的 Web Chat 唯一識別碼
baseUrl	String	是	MaiAgent Web Chat 服務的基礎 URL，建立 Web Chat 之 URL 為POST https://chat.maiagent.ai/web-chats
primaryColor	String	否	聊天視窗的主色調，使用 HEX 色碼格式，例如 #3854d8
allowDrag	Boolean	否	是否允許使用者拖動聊天視窗位置，設定為 true 或 false
contactId	String	否	聯絡人 ID，可至 MaiAgent Admin 設定聯絡人的 queryMetadata，可參考：聯絡人(Contact) 串接 了解獲取 Contact ID 之機制
queryMetadata	Object	否	知識庫搜索範圍設定，詳情請參考：開始建構—使用 JSON 格式

語言設定

嵌入 MaiAgent Web Chat 後，您可以透過 JavaScript 控制聊天介面的文字語言及語音語言設定。

// 設定介面為繁體中文
globalThis.MaiAgent.locale.set('zh-TW') 

// 設定 ASR 及 TTS 使用英文
globalThis.MaiAgent.speech.set('en') 

1. Web Chat 語言與語音控制

• Web Chat 支援繁簡中、英、日、韓、泰等多種語言，未來還會持續擴充

• 嵌入後可全域存取 globalThis.MaiAgent 物件，並設定文字或語音語言

• 除 「 繁體中文 」 及 「 簡體中文 」 以外，其他語言只需指定 「 語言碼 」

2. 語言設定範例

您可以根據網站需求，設定不同的語言介面與語音選項：

• 文字介面：可設定為繁體中文 ( zh-TW )、簡體中文 ( zh-CN )、英文 ( en ) 等

• 語音設定：可設定 ASR ( 語音識別 ) 和 TTS ( 語音合成 ) 使用的語言

3. MaiAgent 目前支援語言

語言碼	語言
zh-TW	繁體中文
zh-CN	簡體中文
en	英文
th	泰文
ms	馬來文
vi	越南文
id	印尼文
fil	菲律賓文
my	緬甸文
km	高棉文
lo	寮文
ja	日文
ko	韓文

注意事項

• 系統經由聯絡人 API 確認已帶有 Contact ID 後才會進行初始化。

• 可使用 Query Metadata 使 Web Chat 在初始化時就帶有知識管理權限

了解更多關於知識管理權限內容，請參考 🌐知識管理權限(Query Metadata / 查詢元資料) 總覽↗