聯絡人 (Contact) 介紹及串接

聯絡人是什麼？

核心定義

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

聯絡人運作方式如下圖：

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

聯絡人串接流程

系統架構概述

企業系統：主要系統，負責用戶管理和 Web Chat 整合
MaiAgent：提供 Web Chat 功能的服務方
通訊協定：RESTful API

對接流程

步驟 1：用戶身份檢查

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

步驟 2：建立或更新 Contact

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

建立新聯絡人

更新現有聯絡人

適用情況

首次訪問且企業系統中尚無對應 Contact，如： 1. 用戶第一次透過 Web Chat 與企業互動 2. 訪客轉為企業中正式會員，須建立專屬聯絡人確保不共用訪客時期對話及權限

會員在企業系統中修改姓名、Email、手機等資訊，需同步更新 MaiAgent 聯絡人資訊，確保後續對話中個人化內容正確當企業會員中有權限、帳號狀態的變動，也應更新聯絡人資訊確保 Web Chat 權限對應正確

API 端點

POST /api/contacts/ 除使用 API 外，也可使用圖形化介面建立聯絡人

PUT /api/contacts/{contact_id}/

功能

建立新的聯絡人對應使用，確保個人化對話服務順暢

更新現有聯絡人的資料，如：Query Metadata 權限管理、更新的會員資料等

參數

需要提供欲建立之聯絡人名稱 (name)，若無會員資料對應則預設為「匿名」 (如：網頁訪客)

需要提供 contact_id

回應

返回新建立的 contact_id

返回更新成功的確認訊息

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

圖形化介面建立聯絡人

進入聯絡人管理介面

點擊「新增聯絡人」

點擊後會出現以下頁面：

新增聯絡人姓名、指定對話平台後即可建立聯絡人資訊，可點擊複製按鍵，複製聯絡人 ID (為 Web Chat 初始化參數 ContactId)

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

👉 了解 Query Metadata

處理邏輯：

企業系統需要妥善保存回傳的 contact_id（Create 時）
建議將 contact_id 與企業系統的用戶 ID 進行關聯存儲
Update 時需要在 URL 路徑中提供現有的 contact_id

步驟 3：初始化 Web Chat

將步驟 2 中拿到的 Contact ID 加入 Web Chat 初始化傳入的參數中並執行初始化腳本。

請參考 🌐Web Chat 初始化↗，進行 Web Chat 初始化

使用說明

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

企業內部權限管理：透過 Contact 設定，管理不同用戶的對話權限範圍
Web Chat 嵌入：當 Web Chat 嵌入至企業網站後，在沒有 MaiAgent 會員資料的情況下，企業可透過 contact 的串接設定來達到對話的權限管理目的
跳過會員建立：對話平台使用者無需進入 MaiAgent 平台註冊，可略過 MaiAgent 成員的建立與角色分配，直接透過 Contact ID 管理對話權限

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

實作建議

建議在企業系統中建立 Contact ID 管理表，包含：
- 企業用戶 ID
- MaiAgent Contact ID
  協助在與 MaiAgent 建立連線時能正確連結企業用戶資料與 MaiAgent 聯絡人
- 建立時間
- 最後更新時間
實作冪等性檢查，避免重複建立 Contact
建立日誌記錄機制，追蹤 API 調用狀況
考慮實作異步處理，提升用戶體驗，將以上 Contact 相關 API 與系統其他 API 同時執行多個請求，減少使用者等待

上一页Web Chat 初始化下一页角色(Role) 和聯絡人(Contact) 的差異

最后更新于16天前

这有帮助吗？