Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

聯絡人 (Contact) 介紹及串接

聯絡人是什麼？

聯絡人（Contact）代表「跟 AI 助理對話的終端使用者」。企業把自家系統的使用者對應到 MaiAgent 聯絡人後，AI 就能認得「誰在問」：正確回溯這個人的對話歷史與權限設定，而不是別人的。

聯絡人不需要 MaiAgent 帳號（這是它與成員／角色最大的差別），使用者也不會感知到它的存在——它是您的系統與 MaiAgent 之間的身份對應。

聯絡人上可以掛什麼

資料
用途
詳細說明

基本資料（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 工具憑證，見下方說明

後台圖形化介面

少量、手動管理的場景

見下方操作說明

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

串接流程

三個步驟：

  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 收件匣

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

匯入的比對與更新規則：

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

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

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

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

圖形化介面建立聯絡人

  1. 進入聯絡人管理介面

  1. 點擊新增聯絡人

聯絡人頁面

點擊後會出現以下頁面：

聯絡人編輯頁面

輸入聯絡人姓名、指定對話平台後即可建立。建立後可點擊複製按鈕取得聯絡人 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 與登入流程其他請求平行執行，失敗不阻擋使用者登入、下次登入重試

上一頁軟體廠商整合指南（端到端）
下一頁聯絡人身份同步與 Token 更新

最後更新於

這有幫助嗎？