Web Chat SDK 操作指令

本篇將介紹如何使用 MaiAgent 的 Web Chat SDK

使用 MaiAgent SDK 提供了一套完整的 JavaScript API，讓開發者可以輕鬆地將 MaiAgent 聊天機器人整合到任何網站中。

一、初始化說明

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

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

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

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

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

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

注意事項

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

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

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

二、快速開始

1. 引入 SDK

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: '<https://yourdomain.com/web-chats>',
    primaryColor: '#1890ff',
    allowDrag: true,
  }
</script>
<script src="<https://yourdomain.com/js/embed.min.js>"></script>

2. 使用 API

// 等待 SDK 初始化完成
document.addEventListener('DOMContentLoaded', () => {
  // 監聽消息回覆
  MaiAgent.events.on('messageReply', (data) => {
    console.log('收到新消息:', data)
  })

  // 發送消息
  MaiAgent.chat.send('你好！')

  // 打開聊天視窗
  MaiAgent.control.open()
})

三、基本配置

在引入 SDK 之前，需要先配置 maiagentChatbotConfig 物件：

詳細參數說明請參考下方 配置選項 說明

window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id', // 必填：聊天機器人 ID
  baseUrl: '<https://yourdomain.com/web-chats>', // 必填：API 基礎 URL
  primaryColor: '#1890ff', // 主題顏色
  allowDrag: true, // 是否允許拖拽按鈕
  buttonSize: '48', // 按鈕大小（像素）
  buttonRadius: '50%', // 按鈕圓角
  buttonPositionBottom: '16', // 按鈕距離底部距離
  buttonPositionRight: '16', // 按鈕距離右側距離
  windowWidth: '24rem', // 聊天視窗寬度
  windowHeight: '40rem', // 聊天視窗高度
  windowRadius: '0.75rem', // 聊天視窗圓角
  windowPositionBottom: '5rem', // 聊天視窗距離底部距離
  windowPositionRight: '1rem', // 聊天視窗距離右側距離
  boxShadow: '0.125rem 0.125rem 0.5rem #00000044', // 陰影效果
  contactId: 'contact-id', // 可選：聯絡人 ID
  queryMetadata: { key: 'value' }, // 可選：查詢元數據
  closeIconHtml: '<svg>...</svg>', // 可選：自定義關閉圖示
  openIconHtml: '<svg>...</svg>' // 可選：自定義開啟圖示
}

四、API 功能

1. 聊天控制

MaiAgent.control.open()

打開聊天視窗

// 打開聊天視窗
MaiAgent.control.open()

MaiAgent.control.close()

關閉聊天視窗

// 關閉聊天視窗
MaiAgent.control.close()

MaiAgent.control.isOpen()

檢查聊天視窗是否開啟

// 檢查聊天視窗狀態
const isOpen = MaiAgent.control.isOpen()
console.log('聊天視窗狀態:', isOpen ? '開啟' : '關閉')

2. 訊息管理

MaiAgent.chat.send(content)

發送消息到聊天機器人

// 發送簡單文字消息
MaiAgent.chat.send('你好，我需要幫助')

MaiAgent.chat.clearHistory()

清除聊天歷史記錄

// 清除所有聊天歷史
MaiAgent.chat.clearHistory()

MaiAgent.chat.newConversation()

開始新的對話

// 開始新對話
MaiAgent.chat.newConversation()

3. 事件監聽

MaiAgent.events.on(eventType, callback)

註冊事件監聽器

// 監聽消息回覆 - 使用字符串
MaiAgent.events.on('messageReply', (data) => {
  console.log('收到回覆:', data)
  // data 包含消息內容、時間戳等資訊
})

// 或者使用 EVENT_TYPES 常量（推薦用於生產環境）
MaiAgent.events.on(MaiAgent.EVENT_TYPES.MESSAGE_REPLY, (data) => {
  console.log('收到回覆:', data)
})

MaiAgent.events.off(eventType, callback)

移除事件監聽器

// 移除特定的事件監聽器
function messageHandler(data) {
  console.log('消息事件:', data)
}

MaiAgent.events.on('messageReply', messageHandler)
// ... 稍後移除
MaiAgent.events.off('messageReply', messageHandler)

4. 語言設定

Web Chat 語言與語音控制

MaiAgent 支援語言說明請參考 多國語言支援

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

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

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

語言設定範例

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

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

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

MaiAgent.speech.set(lang, provider)

設定語音語言和提供商

// 設定語音為中文，使用 Azure 提供商
MaiAgent.speech.set('zh-TW', 'azure')

// 設定語音為英文，使用預設提供商
MaiAgent.speech.set('en-US')

MaiAgent.locale.set(lang)

設定介面語言

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

// 設定為簡體中文
MaiAgent.locale.set('zh-CN')

// 設定為英文
MaiAgent.locale.set('en')

五、配置選項

1. 基本配置

選項	類型	必填	預設值	說明
webChatId	string	是	-	聊天機器人的唯一識別碼
baseUrl	string	是	-	API 服務的基礎 URL
contactId	string	否	-	聯絡人識別碼
queryMetadata	object/string	否	-	額外的查詢元數據

2. 外觀配置

選項	類型	預設值	說明
primaryColor	string	#1890ff	主題顏色
buttonSize	string	48	按鈕大小（像素）
buttonRadius	string	50%	按鈕圓角
windowWidth	string	24rem	聊天視窗寬度
windowHeight	string	40rem	聊天視窗高度
windowRadius	string	0.75rem	聊天視窗圓角
boxShadow	string	0.125rem 0.125rem 0.5rem #00000044	陰影效果

3. 位置配置

選項	類型	預設值	說明
buttonPositionBottom	string	16	按鈕距離底部距離（像素）
buttonPositionRight	string	16	按鈕距離右側距離（像素）
windowPositionBottom	string	5rem	聊天視窗距離底部距離
windowPositionRight	string	1rem	聊天視窗距離右側距離

4. 行為配置

選項	類型	預設值	說明
allowDrag	boolean	true	是否允許拖拽聊天按鈕

5. 自定義圖示

選項	類型	預設值	說明
closeIconHtml	string	預設 SVG	自定義關閉圖示的 HTML
openIconHtml	string	預設 SVG	自定義開啟圖示的 HTML

六、事件類型

1. 可監聽的事件

事件名稱	說明	資料格式
messageReply	收到聊天機器人回覆時觸發	{ content: string, timestamp: number, ... }

2. 內部事件（供參考）

事件名稱	說明
setSpeechLanguage	設定語音語言
setLocale	設定介面語言
sendMessage	發送消息
clearHistory	清除歷史記錄
newConversation	開始新對話
closeBubbleWindow	關閉聊天視窗
sdkReady	SDK 準備就緒

七、完整範例

以下是一個完整的整合範例：

<!doctype html>
<html lang="zh-TW">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>MaiAgent SDK 整合範例</title>
  </head>
  <body>
    <h1>我的網站</h1>
    <p>這裡是網站內容...</p>

    <!-- 一些互動按鈕 -->
    <button onclick="openChatBot()">開啟客服</button>
    <button onclick="sendWelcomeMessage()">發送歡迎消息</button>
    <button onclick="clearChatHistory()">清除對話</button>
    <button onclick="startNewChat()">新對話</button>

    <!-- MaiAgent SDK 配置 -->
    <script>
      window.maiagentChatbotConfig = {
        webChatId: 'your-web-chat-id',
        baseUrl: '<https://your-domain.com/web-chats>',
        primaryColor: '#007bff',
        allowDrag: true,
        buttonSize: '56',
        buttonRadius: '50%',
        windowWidth: '28rem',
        windowHeight: '45rem',
        contactId: 'website-visitor',
        queryMetadata: {
          source: 'website',
          page: window.location.pathname,
        },
      }
    </script>

    <!-- 引入 MaiAgent SDK -->
    <script src="<https://your-domain.com/js/embed.min.js>"></script>

    <!-- 應用程式邏輯 -->
    <script>
      // 等待 DOM 和 SDK 載入完成
      document.addEventListener('DOMContentLoaded', function () {
        // 設定事件監聽器
        setupEventListeners()

        // 設定語言
        MaiAgent.locale.set('zh-TW')
        MaiAgent.speech.set('zh-TW', 'azure')

        console.log('MaiAgent SDK 已就緒')
      })

      function setupEventListeners() {
        // 監聽消息回覆
        MaiAgent.events.on('messageReply', function (data) {
          console.log('收到機器人回覆:', data)

          // 可以在這裡處理回覆，例如：
          // - 收到的 data 為JSON 需要 JSON.parse(data) 一下
          // - 記錄分析數據
          // - 更新 UI 狀態
          // - 觸發其他業務邏輯
        })
      }

      // 互動函數
      function openChatBot() {
        MaiAgent.control.open()
      }

      function closeChatBot() {
        MaiAgent.control.close()
      }

      function sendWelcomeMessage() {
        MaiAgent.chat.send('你好！我想了解你們的服務')

        // 確保聊天視窗是開啟的
        MaiAgent.control.open()
      }

      function clearChatHistory() {
        if (confirm('確定要清除所有對話歷史嗎？')) {
          MaiAgent.chat.clearHistory()
          console.log('對話歷史已清除')
        }
      }

      function startNewChat() {
        MaiAgent.chat.newConversation()
        MaiAgent.control.open()
        console.log('已開始新對話')
      }

      // 監聽頁面可見性變化，在用戶回到頁面時可以發送消息
      document.addEventListener('visibilitychange', function () {
        if (!document.hidden && MaiAgent.control.isOpen()) {
          console.log('用戶回到頁面，聊天視窗仍開啟')
          // 可以在這裡執行一些操作
        }
      })
    </script>
  </body>
</html>

八、進階使用技巧

1. 動態配置更新

// 動態更新主題顏色
function updateTheme(color) {
  // 注意：需要重新初始化才能生效
  window.maiagentChatbotConfig.primaryColor = color
  initializeChatbot()
  // 重新載入 SDK 或重新整理頁面
}

2. 錯誤處理

// 檢查 SDK 是否可用
function checkSDKAvailability() {
  if (typeof MaiAgent === 'undefined') {
    console.error('MaiAgent SDK 未載入')
    return false
  }

  if (!MaiAgent.control) {
    console.error('MaiAgent SDK 未完全初始化')
    return false
  }

  return true
}

// 安全地使用 SDK
function safeOpenChat() {
  if (checkSDKAvailability()) {
    MaiAgent.control.open()
  }
  else {
    alert('聊天服務暫時無法使用，請稍後再試')
  }
}

3. 與其他系統整合

// 與 Google Analytics 整合
MaiAgent.events.on('messageReply', (data) => {
  // 記錄聊天互動事件
  if (typeof gtag !== 'undefined') {
    gtag('event', 'chat_interaction', {
      event_category: 'engagement',
      event_label: 'bot_reply',
      value: 1
    })
  }
})

九、疑難排解

1. 常見問題

1. SDK 未載入

   • 確認 maiagentChatbotConfig 在 SDK 腳本之前定義

   • 檢查網路連線和腳本 URL 是否正確

2. 聊天視窗無法開啟

   • 確認 webChatId 和 baseUrl 配置正確

   • 檢查瀏覽器主控台是否有錯誤訊息

3. 事件監聽器無效

   • 確保在 DOM 載入完成後註冊事件監聽器

   • 檢查事件名稱是否正確

4. 按鈕位置異常

   • 檢查 CSS 衝突

   • 確認位置參數格式正確