WebChat 注入頁面 Context（contextData）

透過 embed SDK 的 auth.contextData，把頁面 context（如商品 ID、工單編號、使用者識別碼）注入 AI 助理的 LLM System Prompt

當 Web Chat 嵌入在您的網站時，AI 助理預設並不知道「使用者目前在哪個頁面、正在看什麼」。contextData 讓嵌入方在 embed 設定中傳入任意 key-value 資料，這些資料會隨每則訊息自動送出，並注入 LLM System Prompt，讓 AI 助理在對話與工具呼叫（Tool / Function Calling）中直接使用。

常見應用：

• 電商商品頁：注入 productId，助理不必反問「您想問哪個商品？」，直接以該商品 ID 呼叫「查商品」API 工具回答

• 客服系統：注入 ticketId、customerId，助理直接引用工單脈絡處理客服流程

• 醫療 / 表單服務：從 QR code 讀取識別碼（如開立序號）注入，助理在呼叫送出 API 時自動帶入

• 會員 / 金融服務：注入會員等級等屬性，助理依身分提供個人化回覆

contextData 掛在 embed 設定的 auth 底下，因此必須同時提供 auth.sourceId（使用者識別碼）。詳細的 auth 機制請參考 Web Chat SDK 操作指令。

一、快速開始

在嵌入腳本前的 maiagentChatbotConfig 中加入 auth.contextData：

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://yourdomain.com/web-chats',
    auth: {
      sourceId: 'user-12345',        // 必填：使用者唯一識別碼
      name: '王小明',                 // 選填：顯示名稱
      contextData: {                 // 任意 key-value，注入 LLM system prompt
        productId: '3021',
        productName: '無線降噪耳機',
      },
    },
  }
</script>
<script src="https://yourdomain.com/js/embed.min.js"></script>

SDK 載入完成後會自動執行 auth.setup()，之後使用者送出的每一則訊息都會在 metadata 中夾帶這些 key-value，後端會將它們以下列格式附加到 System Prompt：

Contact custom attributes:
- productId: 3021
- productName: 無線降噪耳機

AI 助理即可在回答與工具呼叫中直接引用這些值。

二、運作機制

幾個重要特性：

• 隨訊息送出、不落資料庫：contextData 只存在前端記憶體，隨每則訊息的 payload 送出。使用者重新整理頁面後，需由嵌入頁面重新注入（適合 QR code、session 這類短生命週期資料）

• 每輪對話都生效：因為隨每則訊息送出，AI 在整段對話中都能持續取得最新的 context

• 無額外 API 呼叫：沿用既有訊息通道，沒有額外效能負擔

與 queryMetadata 的差異

兩者用途完全不同，請勿混用：

	auth.contextData	queryMetadata
用途	把頁面 context 告訴 AI（進 System Prompt）	控制知識庫檢索範圍（RAG 權限過濾）
LLM 是否讀得到	✅ 出現在 System Prompt	❌ 不進 prompt、不傳給工具
適用情境	商品 ID、工單編號、使用者識別碼	知識管理權限、文件存取範圍

如果您想讓 AI「知道」某個值（例如讓它填入 API 工具參數），請使用 contextData；如果想限制 AI「查得到哪些知識文件」，請使用 知識管理權限（Query Metadata）。

三、資料規則與限制

SDK 會對傳入的 contextData 做淨化（sanitize），規則如下：

規則	行為
value 型別	支援 string；number / boolean 自動轉為字串；其餘型別（object、array、null…）該 key 直接丟棄
key 數量上限	最多 50 組 key-value，超過的部分丟棄
保留 key	與系統既有 metadata 衝突的 key 會被丟棄（見下方清單）
空物件 {}	淨化後為空，視同未傳，metadata 不含自訂 key
淨化方式	靜默處理，不會報錯、不阻斷送訊

保留 key 清單（傳入會被丟棄，避免覆蓋系統欄位）：

contact_name、timezone、latitude、longitude、accuracy、locale、language、working_directory

安全性由嵌入方負責：contextData 由嵌入頁面注入，MaiAgent 不對其來源做簽章或加密驗證。請勿注入不應讓終端使用者得知的機密資料（值會進入 LLM prompt，AI 可能在回覆中複述）；若資料具識別性（如身分證字號），請由嵌入方確保來源可信（例如經簽章的 QR code / session）並符合個資合規要求。

四、更新與清除

contextData 的生命週期跟隨 auth.setup()：

• 更新：再次呼叫 MaiAgent.auth.setup() 會整份覆寫目前的 contextData（不是合併）

• 清除：auth.setup() 時不帶 contextData，即清空先前注入的值；MaiAgent.auth.signOut() 也會一併清空，避免跨身分殘留

// SPA 切換頁面時，更新 context 為新商品
MaiAgent.auth.setup({
  sourceId: 'user-12345',
  contextData: {
    productId: '4552',
    productName: '攜帶式藍牙喇叭',
  },
})

// 離開商品頁時，清空 context（不帶 contextData 即清空）
MaiAgent.auth.setup({
  sourceId: 'user-12345',
})

五、應用範例

1. 電商商品頁：AI 依當前商品回答

情境：AI 助理設定了「查商品」API 工具（以商品 ID 查詢商品詳情）。Web Chat 嵌入在商品詳細頁，希望使用者問「這個適合我嗎？」時，助理不反問、直接針對當前商品回答。

<!-- 商品詳細頁，例如 product_detail.php?id=3021 -->
<script>
  // 從頁面取得當前商品資訊（依您的網站實作方式取得）
  const productId = new URLSearchParams(location.search).get('id')

  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://yourdomain.com/web-chats',
    auth: {
      sourceId: 'visitor-' + productId,   // 依您的會員 / 訪客識別邏輯
      contextData: {
        productId,                         // AI 呼叫「查商品」工具時填入此 ID
        productName: document.querySelector('.product-title')?.textContent ?? '',
      },
    },
  }
</script>
<script src="https://yourdomain.com/js/embed.min.js"></script>

使用者問「這款的續航力可以用多久？」時，System Prompt 已包含 productId: 3021，AI 直接以 id=3021 呼叫「查商品」工具取得商品詳情後回答，不需反問「您想問哪個商品？」。

建議搭配角色指令引導：context 是否被工具實際使用，由 LLM 依 prompt 判斷。在 AI 助理的角色指令中明確引導可大幅提升穩定度，例如：「當 Contact custom attributes 中有 productId 時，代表使用者正在瀏覽該商品，請優先以此 ID 呼叫查商品工具回答，不要反問使用者。」

2. 客服系統：帶入工單脈絡

window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://yourdomain.com/web-chats',
  auth: {
    sourceId: currentUser.id,
    name: currentUser.displayName,
    contextData: {
      ticketId: 'T-2026-0142',
      customerId: currentUser.id,
      plan: 'enterprise',
    },
  },
}

使用者開啟對話後，AI 已知工單編號與客戶方案等級，可直接處理該工單的後續流程，不需客戶重複說明。

3. 識別碼注入：QR code / URL 參數

情境：服務網頁由 QR code 或帶參數的連結開啟，需要讓 AI 在呼叫送出 API 時自動帶入識別碼。

const params = new URLSearchParams(location.search)

window.maiagentChatbotConfig = {
  webChatId: 'your-web-chat-id',
  baseUrl: 'https://yourdomain.com/web-chats',
  auth: {
    sourceId: params.get('sessionId'),
    contextData: {
      formId: params.get('formId'),       // 表單 / 單據識別碼
      userRef: params.get('userRef'),     // 使用者參考編號
    },
  },
}

AI 引導使用者完成流程後，呼叫送出工具（如 SubmitAnswers）時自動將 formId、userRef 填入 request body。

六、驗證與疑難排解

如何確認 contextData 有生效？

1. 開啟瀏覽器開發者工具的 Network 分頁，觀察 WebSocket 訊息：送出的訊息 payload 中 metadata 應包含您注入的 key

2. 直接問 AI 助理：「你知道我的 productId 是什麼嗎？」——若注入成功，AI 能直接回答

3. 在管理後台的對話監控中檢視該則訊息實際使用的 prompt，應包含 Contact custom attributes 區塊

常見問題

問題	原因與處理
contextData 完全沒生效	確認有提供 auth.sourceId（必填，缺少時 auth.setup() 不會執行）
某些 key 消失了	檢查是否用到保留 key、value 是否為不支援的型別（object / array）、或超過 50 組上限
重新整理後 context 不見了	預期行為：不落資料庫，需由頁面在每次載入時重新注入
AI 沒有使用 context 呼叫工具	在角色指令中明確引導（見上方範例 1 的 hint）