聯絡人 (Contact) 介紹及串接

聯絡人（Contact）介紹及串接：以 sourceId 把自家系統使用者對應到終端使用者，建立與同步聯絡人的四種方式、Excel 批次匯入與實作建議。

聯絡人是什麼？

聯絡人（Contact）代表「跟 Agent 對話的終端使用者」，不需要 MaiAgent 帳號。企業把自家系統的使用者以 sourceId 對應到聯絡人後，AI 就能認得「誰在問」，正確回溯這個人的對話歷史與權限設定。聯絡人的概念、匿名與非匿名聯絡人的差別，以及後台操作，見使用者手冊聯絡人；和成員／角色的差別見角色和聯絡人的差異。本頁只寫 API 串接。

聯絡人上可以掛什麼

資料	用途	詳細說明
基本資料（name、email、avatar）	顯示在後台聯絡人列表與對話記錄	本頁下方 API 說明
自訂屬性（metadata）	部門、會員等級等背景資料，AI 會讀取並帶入回答	聯絡人身分同步與 Token 更新
查詢元資料（query_metadata）	限制該使用者可檢索的知識庫／文件／標籤範圍	知識管理權限（Query Metadata）
MCP／API 工具憑證	讓 AI 以該使用者的身分與權限呼叫外部工具	聯絡人身分同步與 Token 更新
對話歷史	跨裝置延續對話	前端帶 contactId 即生效

建立與同步聯絡人的四條路

方式	適合	說明
身分同步 API（setup-contact-credentials）	使用者登入時同步、要綁工具憑證、既有系統批次補建	冪等（同 sourceId 不重複建立）、免 API Key。含 Web Chat 前端 auth 自動呼叫的版本。多數串接場景建議走這條，詳見聯絡人身分同步與 Token 更新
聯絡人 API（POST /api/v1/contacts/）	後端完全掌控聯絡人生命週期、需要建立時就設定 query_metadata	需要 API Key；更新用 PATCH /api/v1/contacts/{contact_id}/（只更新有傳入的欄位）。schema 見 API 文件-聯絡人
批次匯入（Excel）	既有系統首次串接，一次補建大量使用者	上限 10,000 列，可同時帶 query_metadata 與 API 工具憑證，見下方說明
後台圖形化介面	少量、手動管理的場景	見下方操作說明

四條路建立的是同一種聯絡人，可混用（例如首次串接用批次匯入、日常登入走身分同步）。

聯絡人 API 的請求欄位

POST /api/v1/contacts/ 的請求內容（camelCase 與 snake_case 都接受）：

欄位	必填	說明
name	是	顯示名稱，最長 255 字元
inboxes	是（二擇一）	[{"id": "<對話平台 ID>"}]，聯絡人所屬的對話平台，必須屬於金鑰所在的組織；舊欄位 inbox（單一 {"id": …}）仍接受，兩者都帶時以 inboxes 為準，都沒帶回 400
sourceId	否	您系統中的使用者 ID，最長 255 字元。同一個對話平台內不可重複，重複回 400；沒帶時這位聯絡人只能用 contactId 識別
email、phoneNumber、avatar	否	基本資料；avatar 可填完整網址或平台相對路徑
metadata	否	自訂屬性，鍵值陣列格式見聯絡人身分同步與 Token 更新
queryMetadata	否	知識檢索範圍，格式見 Query Metadata

最小的有效請求是 {"name": "王小明", "inboxes": [{"id": "<對話平台 ID>"}]}。回應 201 帶完整聯絡人物件，其中 mcpCredentials、apiCredentials、contactConnectors、tags 是唯讀欄位，憑證要用各自的端點寫入。

聯絡人的歸屬與可見範圍

聯絡人屬於組織，不屬於建立它的 API 金鑰：同一組織內任何一把金鑰，只要綁定的成員具備聯絡人權限，都能讀取、更新與刪除同一位聯絡人；輪替金鑰後 contactId 與 sourceId 都照常可用。跨組織則完全看不到（回 404）。

成員登入後會不會變成聯絡人？

會，但不是在登入時：成員（含 SSO 登入的成員）在 MaiGPT、後台測試對話等以平台帳號發起對話時，平台會在該對話平台上為這位成員建立（或沿用）一位 sourceId 等於其使用者 ID、並連結到該帳號的聯絡人；用 API 金鑰呼叫 completions 而不帶 sender 時也是同一條規則（見省略 message.sender 時的身分）。因此掛在這位聯絡人上的 MCP／API 工具憑證與 queryMetadata，在成員自己的對話中同樣生效；聯絡人是依對話平台建立的，同一位成員在不同對話平台會有不同的聯絡人。成員的角色權限與聯絡人設定各自獨立，見角色(Role) 和 聯絡人(Contact) 的差異。

串接流程

三個步驟：

1. 檢查對應：以企業系統的 user ID 查會員資料，確認是否已有 MaiAgent contact_id

2. 建立或更新：沒有就建立（存回 contact_id）；使用者改了姓名／Email、或權限異動時，同步更新聯絡人（PATCH /api/v1/contacts/{contact_id}/），確保後續對話的個人化內容與權限正確

3. 初始化 Web Chat：前端 config 帶 contactId，見 Web Chat 嵌入與 SDK

若您的場景是「使用者登入企業系統時，同步建立聯絡人並更新 Token 憑證」（例如讓 AI 以使用者權限呼叫 MCP 工具），請參考聯絡人身分同步與 Token 更新，一次呼叫即可完成聯絡人建立與憑證綁定。

聯絡人批次匯入（Excel）

既有系統首次串接時，用 Excel 一次補建（或更新）大量聯絡人：

1

下載模板

GET /api/v1/contacts/bulk-import-template/ 下載 Excel 模板（含標題列與範例列）。

2

填入資料

欄位	必填	說明
Name(required)	✅	聯絡人顯示名稱
Email(required)	✅	比對鍵之一（不分大小寫）
Phone Number		電話
Source ID(required)	✅	企業系統的使用者識別碼，比對鍵之一；請使用不可猜測的值（同身分同步 API 的安全提醒）
Query Metadata		JSON 物件，寫入聯絡人的知識查詢範圍；空白儲存格＝保留既有值。格式見 JSON 格式指南
API Credentials		JSON 陣列 [{"tool": "<工具 ID>", "headers": {...}}]，綁定 API 工具憑證；空白＝保留既有憑證

3

上傳匯入

POST /api/v1/contacts/bulk-import/（multipart/form-data，Authorization: Api-Key 認證，與聯絡人 API 相同）：

• file：填好的 .xlsx（上限 10 MB、10,000 列）

• inboxes：收件匣 UUID 清單（至少一個）；之後要走 Web Chat 登入同步，請確認包含對應的 Web Chat 收件匣

• inboxMode（選填，預設 replace）：replace 時，每個匯入的聯絡人的收件匣集合會被整份取代為 inboxes；merge 時只加入 inboxes，保留聯絡人既有的收件匣

• dryRun（選填，預設 false）：true 時只解析與驗證檔案、回報將新增與更新的筆數，不寫入任何資料（回 200；正式匯入回 201）

回應：{ "created": N, "updated": M, "dryRun": false }

建議先以 dryRun=true 送一次，確認筆數符合預期再正式匯入。

匯入的比對與更新規則：

• 以（Source ID、Email）為鍵做 upsert：命中既有聯絡人時更新姓名／電話／Query Metadata（空白儲存格不動），未命中則建立

• API Credentials 以（聯絡人、工具）為鍵 upsert；檔案中未提及的工具憑證不會被動到

• 整批在同一交易內完成：任一列格式錯誤（如欄位名不符、JSON 不合法）整批不寫入，錯誤訊息會標明列號

匯入只建立對應與屬性；使用者的 Token 憑證仍由登入流程的身分同步 API 在每次登入時更新。

圖形化介面建立聯絡人

少量聯絡人可以在後台手動新增或以 Excel 批次匯入（含預覽），步驟見使用者手冊新增聯絡人與批次匯入聯絡人。建立後可在聯絡人列表複製聯絡人 ID，即 Web Chat 初始化參數 contactId。

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

👉 了解 Query Metadata

實作建議

1. 會員資料表加一個對應欄位（如 maiagent_contact_id，UUID、nullable），連同建立／更新時間一起記錄，確保企業 user ID ↔ Contact ID 的對應可追溯

2. 實作冪等：建立前先查對應，或直接走身分同步 API（sourceId 冪等，重跑不會產生重複聯絡人）

3. 記錄 API 呼叫 log，方便追查對應異常

4. 非同步呼叫：聯絡人相關 API 與登入流程其他請求平行執行，失敗不阻擋使用者登入、下次登入重試