聯絡人 (Contact) 串接

使用說明

Contact 對話權限功能主要用於以下場景：

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

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

• 跳過會員建立：可略過 MaiAgent 成員的建立與角色分配，直接透過 Contact ID 管理對話權限

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

系統架構概述

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

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

• 通訊協定：RESTful API

對接流程

步驟 1：用戶身份檢查

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

步驟 2：建立或更新 Contact

如果用戶尚未在 MaiAgent 系統註冊，需要調用 Create Contact API；如果已存在但需要更新資料，則調用 Update Contact API。

Create Contact API 端點： POST /api/contacts

Update Contact API 端點： PUT /api/contacts/{contact_id}

API 請求參數說明（Create / Update Contact）

name	string	是	用戶名稱，用於識別此聯絡人
avatar	string (URL)	否	用戶頭像圖片的 URL，可選填
source_id	string	否	外部系統用戶唯一識別碼（如：網智的用戶 ID）
inbox	string	是	MaiAgent 的對話平台 ID
query_metadata	object	否	權限控制用的查詢條件設定，詳細說明如下

query_metadata 欄位說明

label_relations	object	否	查詢所需標籤條件，可設定單層或巢狀 AND/OR 條件邏輯
label_relations.operator	string	否	主邏輯運算子，支援 "AND" 或 "OR"
label_relations.conditions	array	否	條件陣列，可為單一 label_id 或巢狀邏輯組合
label_relations.conditions[].label_id	string (UUID)	否	指定的標籤 ID
label_relations.conditions[].operator	string	否	巢狀邏輯的運算子（"AND" 或 "OR"）
label_relations.conditions[].conditions	array	否	巢狀邏輯條件的子項陣列
knowledge_bases	array	否	指定可存取的知識庫清單（如不設定則無法查詢）
knowledge_bases[].knowledge_base_id	string (UUID)	否	指定的知識庫 ID
knowledge_bases[].chatbot_file_ids	array of string (UUID)	否	該知識庫下可查詢的 chatbot 檔案清單
knowledge_bases[].faq_ids	array of string (UUID)	否	該知識庫下可查詢的 FAQ 文件清單
knowledge_bases[].has_user_selected_all	string ("True" / "False")	否	使用者是否選擇查詢此知識庫下所有內容（字串格式布林值）

請求標頭：

Authorization: Api-Key <您的API金鑰>
Content-Type: application/json

請求參數（兩個 API 相同）：

{
  "name": "string",          // 用戶姓名
  "avatar": "url",           // 用戶頭像 URL
  "source_id": "source_id",  // 網智的用戶 ID
  "inbox": "inbox_id",       // MaiAgent 的對話平台 ID
  "query_metadata": {        // 用戶查詢相關的元數據（詳細格式見下方說明）
    "label_relations": {},
    "knowledge_bases": []
  }
}

query_metadata 格式說明：

{
  "query_metadata": {
    "label_relations": {
      "operator": "OR",               // 邏輯運算子：OR 或 AND
      "conditions": [                 // 條件陣列
        {"label_id": "957998f9-1824-4872-becd-b7f8a7962896"},  // 單一標籤條件
        {
          "operator": "AND",          // 嵌套邏輯運算子
          "conditions": [             // 嵌套條件
            {"label_id": "043d3dfa-cafa-4dba-a622-d83acbcb7c30"},
            {"label_id": "c8aaa53b-3e1b-476e-b575-91072f481dfa"}
          ]
        }
      ]
    },
    "knowledge_bases": [              // 知識庫設定陣列
      {
        "knowledge_base_id": "5f8c6a99-5515-43aa-8e83-fdeea327a3a2",  // 知識庫 ID
        "chatbot_file_ids": ["f5abb2b6-77cf-475d-bc27-e3a41fc0c9a3"], // 聊天機器人檔案 ID 陣列
        "faq_ids": [],                // FAQ ID 陣列（可為空）
        "has_user_selected_all": "False"  // 是否選擇全部（字串格式的布林值）
      }
    ]
  }
}

query_metadata 參數說明：

• label_relations：定義標籤之間的邏輯關係，支援 OR/AND 運算，可以嵌套使用

• knowledge_bases：指定該用戶可以查詢的知識庫範圍和相關檔案

Create Contact 回應：

{
  "contact_id": "string",    // MaiAgent 生成的聯絡人 ID
  "name": "string",          // 用戶姓名
  "avatar": "string",        // 用戶頭像 URL
  "source_id": "string",     // 企業系統的用戶 ID
  "created_at": "string",    // 建立時間戳記
  "updated_at": "string"     // 更新時間戳記
}

Update Contact 回應：

{
  "contact_id": "string",    // 更新的聯絡人 ID
  "name": "string",          // 更新後的用戶姓名
  "avatar": "string",        // 更新後的用戶頭像 URL
  "source_id": "string",     // 企業系統的用戶 ID
  "created_at": "string",    // 建立時間戳記
  "updated_at": "string"     // 更新時間戳記
}

處理邏輯：

• 企業系統需要妥善保存回傳的 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
  };
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>

初始化說明：

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

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

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

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

完整流程圖

flowchart TD
    A[開始] --> B[檢查用戶是否有 contact_id]
    B --> C{已存在?}
    C -->|否| D[調用 Create Contact API]
    C -->|是| E{需要更新?}
    E -->|是| F[調用 Update Contact API]
    E -->|否| G[帶入 contactId 到 maiagentChatbotConfig]
    D --> H[保存 contact_id]
    F --> I[更新 contact_id]
    H --> G
    I --> G
    G --> J[初始化 Web Chat]
    J --> K[完成]

實作建議

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

   • 企業用戶 ID

   • MaiAgent contact_id

   • 創建時間

   • 最後更新時間

2. 實作冪等性檢查，避免重複創建 contact

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

4. 考慮實作異步處理，提升用戶體驗