聯絡人 (Contact) 串接

聯絡人是什麼？

🎯 核心定義

聯絡人（Contact）是 MaiAgent 中一個重要的資訊載體，它讓企業能夠將客戶資料與 MaiAgent 服務進行同步，實現精確的權限管理和個性化服務。

聯絡人運作方式如下圖：

MaiAgent 能透過該客戶在 MaiAgent 中與企業客戶資料相對應的聯絡人資訊（Contact），正確回溯有關該消費者的過去記憶資訊與權限管理內容，而非其他消費者的無關資訊或權限設定。

聯絡人串接流程

系統架構概述

• 企業系統：主要系統，負責用戶管理和 Web Chat 整合

• MaiAgent：提供 Web Chat 功能的服務方

• 通訊協定：RESTful API

對接流程

步驟 1：用戶身份檢查

企業系統需要檢查當前用戶是否已在 MaiAgent 系統中註冊過 Contact。

步驟 2：建立或更新 Contact

依步驟 1 結果決定是否建立新聯絡人

	建立新聯絡人	更新現有聯絡人
適用情況	用戶尚未在 MaiAgent 系統註冊	用戶已擁有 MaiAgent 帳戶
API 端點	POST /api/contacts/	PUT /api/contacts/{contact_id}/
功能	建立新的聯絡人記錄	更新現有聯絡人的資料
參數	需要提供欲建立之聯絡人名稱	需要提供 contact_id
回應	返回新建立的 contact_id	返回更新成功的確認訊息

詳細 schema 內容可參考 🌐 API 文件-聯絡人↗

聯絡人 Contact 所設定的身份資訊，將用於查詢時產生對應的 query_metadata 條件組合

👉 了解 Query Metadata

處理邏輯：

• 企業系統需要妥善保存回傳的 contact_id（Create 時）

• 建議將 contact_id 與企業系統的用戶 ID 進行關聯存儲

• Update 時需要在 URL 路徑中提供現有的 contact_id

步驟 3：初始化 Web Chat

經由上個步驟確認獲得 contact_id 後，系統才會開始初始化 MaiAgent 的 Web Chat：

配置方式：

<script>
  window.maiagentChatbotConfig = {
    webChatId: '從 Admin 嵌入視窗中獲得的 Web Chat ID',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#3854d8',
    allowDrag: true,
    contactId: '從步驟2獲得的contact_id',  // 整合 contact_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，通常為 https://chat.maiagent.ai/web-chats
primaryColor	String	否	聊天視窗的主色調，使用 HEX 色碼格式，例如 #3854d8
allowDrag	Boolean	否	是否允許使用者拖動聊天視窗位置，設定為 true 或 false
queryMetadata	Object	否	知識庫搜索範圍設定，詳情請參考：開始建構—使用 JSON 格式
contactId	String	否	聯絡人 ID，可至 MaiAgent Admin 設定聯絡人的 queryMetadata

初始化說明：

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

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

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

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

使用說明

企業可基於不同的對話需求，自由設置該聯絡人可查看的資料等權限， Contact 對話權限功能主要用於以下場景：

• 企業內部權限管理：透過 Contact 設定，管理不同用戶的對話權限範圍

• Web Chat 嵌入：當 Web Chat 嵌入至企業網站後，在沒有 MaiAgent 會員資料的情況下，企業可透過 contact 的串接設定來達到對話的權限管理目的

• 跳過會員建立：對話平台使用者無需進入 MaiAgent 平台註冊，可略過 MaiAgent 成員的建立與角色分配，直接透過 Contact ID 管理對話權限

此功能特別適用於需要細緻權限控制的企業應用場景。

實作建議

1. 建議在企業系統中建立 Contact ID 管理表，包含：

   • 企業用戶 ID

   • MaiAgent Contact ID

     {% hint style="info" %}協助在與 MaiAgent 建立連線時能正確連結企業用戶資料與 MaiAgent 聯絡人。 {% endhint %} * 建立時間

   • 最後更新時間

2. 實作冪等性檢查，避免重複建立 Contact

3. 建立日誌記錄機制，追蹤 API 調用狀況

4. 考慮實作異步處理，提升用戶體驗，將以上 Contact 相關 API 與系統其他 API 同時執行多個請求，減少使用者等待