軟體廠商整合指南（端到端）

軟體廠商將 Web Chat 嵌入自家產品並完成權限對接的端到端指南：嵌入、批次補建、登入同步、Token 刷新與登出註銷

本頁適合「把 MaiAgent Web Chat 嵌入自家產品、並與自家帳號系統做權限對接」的軟體廠商：使用者在您的系統登入後，AI 助理認得他是誰、能回溯他的對話歷史，並以他的權限呼叫您系統的 API。

整合旅程共五個階段，本頁說明每個階段做什麼、按什麼順序做，細節分別連結到對應的技術文件。

整合全景

核心概念只有一個：聯絡人（Contact）——您系統的每個使用者，對應到 MaiAgent 的一個聯絡人。聯絡人上掛著對話歷史、個人化屬性、知識庫查詢範圍與工具憑證；權限對接的所有動作，本質上都是在維護「您的使用者 ↔ 聯絡人」這條對應與其憑證。概念介紹見聯絡人 (Contact) 介紹及串接。

前後端各自負責什麼

整條旅程中，您的前端只負責「載入聊天視窗」，所有帶 Token 或 API Key 的呼叫都由您的後端發起：

其中 setup-contact-credentials 免 API Key（公開端點）；bulk-import、PATCH、DELETE 都需要 Authorization: Api-Key 認證，只能從後端呼叫。

步驟一：嵌入 Web Chat

依產品形態選擇嵌入方式，兩種用的是同一套 SDK 與同一套聯絡人機制：

形態

適合

文件

聊天泡泡（floating／sidebar）

客服、諮詢等輔助功能

Web Chat 嵌入與 SDK

MaiGPT 模式（類 ChatGPT 完整介面）

頁面主功能區塊、全站 AI 入口

MaiGPT 模式嵌入

要做身份對接的 Web Chat，建議此時就設定「允許嵌入網域」清單（目前由 MaiAgent 團隊為您設定，請提供網域清單給對接窗口），縮小可呼叫身份同步 API 的來源，見允許嵌入網域。

步驟二：首次整合——批次補建既有使用者

既有系統首次串接時，先把現有使用者的聯絡人一次補建起來，有兩條路：

方式

適合

文件

Excel 批次匯入（POST /contacts/bulk-import/）

大量使用者（上限 10,000 列／次），可同時帶入知識查詢範圍與 API 工具憑證

聯絡人批次匯入

逐筆呼叫身份同步 API

順著登入流程漸進補建、或量小

既有使用者批次補建

補建當下拿不到使用者的 Access Token 沒有關係——先建立對應即可，Token 憑證由步驟四的登入流程在各使用者下次登入時補上。

步驟三：新增使用者時建立聯絡人

補建完成後，在您系統的「建立帳號」流程中加一次 API 呼叫，讓新使用者一進來就有對應的聯絡人：

後端呼叫身份同步 API（setup-contact-credentials），以您系統的使用者識別碼作為 sourceId
把回傳的 contactId 存入會員資料表（建議欄位設計見登入流程整合位置）

sourceId 是冪等鍵：同一個 sourceId 重複呼叫只會更新、不會重複建立，所以這一步與步驟二、步驟四可以安全並存。

每次登入成功、產生 Access Token 後，後端再呼叫一次同一支身份同步 API，帶入新的 Token（mcpCredentials），讓 AI 助理能以該使用者的身份與權限呼叫您系統的 API；Token 刷新時也是同一招——再呼叫一次即可，同一組（聯絡人、工具）為更新而非重複建立。完整序列圖與注意事項（非同步呼叫、失敗不阻擋登入）見聯絡人身份同步與 Token 更新。

前端則在頁面初始化 Web Chat 時帶入 contactId，見識別使用者。

若不需要讓 AI 呼叫您系統的 API、只要認得使用者，也可以完全不經後端：前端 config 帶 auth 即可，取捨見前端 auth 與後端串接怎麼選。