> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/authorization-integration/vendor-integration-guide.md). # 軟體廠商整合指南（端到端） 軟體廠商將 Web Chat 嵌入自家產品並完成權限對接的端到端指南：嵌入、批次補建、登入同步、Token 刷新與登出註銷 本頁適合「把 MaiAgent Web Chat 嵌入自家產品、並與自家帳號系統做權限對接」的軟體廠商：使用者在您的系統登入後，AI 助理認得他是誰、能回溯他的對話歷史，並以**他的權限**呼叫您系統的 API。 整合旅程共五個階段，本頁說明每個階段做什麼、按什麼順序做，細節分別連結到對應的技術文件。 ## 整合全景 ```mermaid flowchart LR subgraph ONCE["一次性建置"] A["嵌入 Web Chat"] --> B["批次補建既有使用者"] end subgraph DAILY["日常營運（帳號生命週期）"] C["新增使用者時建立聯絡人"] --> D["登入時更新 Token"] D --> E["Token 刷新時再同步"] E --> F["登出時註銷憑證"] end ONCE --> DAILY ``` 核心概念只有一個：**聯絡人（Contact）**——您系統的每個使用者，對應到 MaiAgent 的一個聯絡人。聯絡人上掛著對話歷史、個人化屬性、知識庫查詢範圍與工具憑證；權限對接的所有動作，本質上都是在維護「您的使用者 ↔ 聯絡人」這條對應與其憑證。概念介紹見[聯絡人 (Contact) 介紹及串接](/tech/authorization-integration/contacts.md)。 ### 前後端各自負責什麼 整條旅程中，您的前端只負責「載入聊天視窗」，所有帶 Token 或 API Key 的呼叫都由您的後端發起： ```mermaid flowchart LR subgraph FE["您的前端"] A["嵌入碼載入 SDK
config 帶 contactId"] B["登出時呼叫 signOut"] end subgraph BE["您的後端"] C["登入／刷新：POST setup-contact-credentials"] D["批次補建：POST bulk-import"] E["資料同步：PATCH contacts"] F["登出：DELETE 工具憑證"] end subgraph MA["MaiAgent"] G["聊天視窗
chat.maiagent.ai"] H["API
api.maiagent.ai"] end A --> G B --> G C --> H D --> H E --> H F --> H ``` 其中 `setup-contact-credentials` 免 API Key（公開端點）；`bulk-import`、`PATCH`、`DELETE` 都需要 `Authorization: Api-Key` 認證，只能從後端呼叫。 ## 步驟一：嵌入 Web Chat {% hint style="warning" %} **先決定要嵌入哪個 AI 助理。** 嵌入的能力（會不會生圖、上網、呼叫工具）取決於 Web Chat 背後的助理設定，不取決於嵌入方式。組織內建的「MaiGPT」產品只供登入成員使用，其 Web Chat **不能**嵌入外部系統；請為您的產品自建一個 AI 助理、設成 Agent 模式並掛上需要的工具，見[串接 MaiGPT：選對助理、補齊能力](/tech/api-integration/web-chat-sdk/maigpt-integration.md)。 {% endhint %} 依產品形態選擇嵌入方式，兩種用的是同一套 SDK 與同一套聯絡人機制： | 形態 | 適合 | 文件 | | ------------------------- | ---------------- | ------------------------------------------------------------------------- | | 聊天泡泡（floating／sidebar） | 客服、諮詢等輔助功能 | [Web Chat 嵌入與 SDK](/tech/api-integration/web-chat-sdk.md) | | MaiGPT 模式（類 ChatGPT 完整介面） | 頁面主功能區塊、全站 AI 入口 | [MaiGPT 模式嵌入](/tech/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | {% hint style="info" %} 要做身份對接的 Web Chat，建議此時就設定「允許嵌入網域」清單（目前由 MaiAgent 團隊為您設定，請提供網域清單給對接窗口），縮小可呼叫身份同步 API 的來源，見[允許嵌入網域](/tech/api-integration/web-chat-sdk.md#embed-origin-allowlist)。 {% endhint %} ## 步驟二：首次整合——批次補建既有使用者 既有系統首次串接時，先把現有使用者的聯絡人一次補建起來，有兩條路： | 方式 | 適合 | 文件 | | --------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------- | | **Excel 批次匯入**（`POST /contacts/bulk-import/`） | 大量使用者（上限 10,000 列／次），可同時帶入知識查詢範圍與 API 工具憑證 | [聯絡人批次匯入](/tech/authorization-integration/contacts.md#bulk-import) | | **逐筆呼叫身份同步 API** | 順著登入流程漸進補建、或量小 | [既有使用者批次補建](/tech/authorization-integration/contact-credentials-sync.md#backfill) | 補建當下拿不到使用者的 Access Token 沒有關係——先建立對應即可，Token 憑證由步驟四的登入流程在各使用者下次登入時補上。 ## 步驟三：新增使用者時建立聯絡人 補建完成後，在您系統的「建立帳號」流程中加一次 API 呼叫，讓新使用者一進來就有對應的聯絡人： * 後端呼叫[身份同步 API（`setup-contact-credentials`）](/tech/authorization-integration/contact-credentials-sync.md)，以您系統的使用者識別碼作為 `sourceId` * 把回傳的 `contactId` 存入會員資料表（建議欄位設計見[登入流程整合位置](/tech/authorization-integration/contact-credentials-sync.md#login-flow)） `sourceId` 是冪等鍵：同一個 `sourceId` 重複呼叫只會更新、不會重複建立，所以這一步與步驟二、步驟四可以安全並存。 ## 步驟四：登入與 Token 刷新 每次登入成功、產生 Access Token 後，後端再呼叫一次同一支身份同步 API，帶入**新的 Token**（`mcpCredentials`），讓 AI 助理能以該使用者的身份與權限呼叫您系統的 API；Token 刷新時也是同一招——再呼叫一次即可，同一組（聯絡人、工具）為更新而非重複建立。完整序列圖與注意事項（非同步呼叫、失敗不阻擋登入）見[聯絡人身份同步與 Token 更新](/tech/authorization-integration/contact-credentials-sync.md)。 前端則在頁面初始化 Web Chat 時帶入 `contactId`，見[識別使用者](/tech/api-integration/web-chat-sdk.md#identify-users)。 {% hint style="info" %} 若不需要讓 AI 呼叫您系統的 API、只要認得使用者，也可以完全不經後端：前端 config 帶 `auth` 即可，取捨見[前端 auth 與後端串接怎麼選](/tech/authorization-integration/contact-credentials-sync.md#frontend-vs-backend)。 {% endhint %} ## 步驟五：登出與憑證註銷 登出時有兩件事，作用範圍不同、建議都做： * **前端**：呼叫 SDK 的 `signOut()`，聊天視窗回到匿名狀態 * **後端**：刪除該聯絡人的工具憑證，讓 AI 即刻無法再以該使用者身份呼叫工具 詳細 API 與兩者的差異對照見[登出與憑證註銷](/tech/authorization-integration/contact-credentials-sync.md#logout-revoke)。 ## 整合檢查清單 | 階段 | 動作 | 文件 | | -- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 建置 | 自建 AI 助理：Agent 模式＋掛上生圖等工具＋建立 Web Chat | [串接 MaiGPT：選對助理、補齊能力](/tech/api-integration/web-chat-sdk/maigpt-integration.md) | | 建置 | 嵌入 Web Chat（一般或 MaiGPT 模式） | [Web Chat 嵌入與 SDK](/tech/api-integration/web-chat-sdk.md)／[MaiGPT 模式](/tech/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | | 建置 | 提供網域清單給 MaiAgent 設定「允許嵌入網域」 | [允許嵌入網域](/tech/api-integration/web-chat-sdk.md#embed-origin-allowlist) | | 建置 | 會員資料表加 `maiagent_contact_id` 欄位 | [登入流程整合位置](/tech/authorization-integration/contact-credentials-sync.md#login-flow) | | 建置 | 批次補建既有使用者 | [聯絡人批次匯入](/tech/authorization-integration/contacts.md#bulk-import) | | 營運 | 建立帳號流程呼叫身份同步 API | [聯絡人身份同步與 Token 更新](/tech/authorization-integration/contact-credentials-sync.md) | | 營運 | 登入／Token 刷新流程更新憑證 | [呼叫時機](/tech/authorization-integration/contact-credentials-sync.md#when-to-call) | | 營運 | 登出流程註銷憑證 | [登出與憑證註銷](/tech/authorization-integration/contact-credentials-sync.md#logout-revoke) | | 進階 | 同步部門、會員等級等個人化屬性 | [同步聯絡人資料](/tech/authorization-integration/contact-credentials-sync.md#sync-contact-profile) | | 進階 | 以查詢元資料限制各使用者的知識庫檢索範圍 | [知識管理權限（Query Metadata）](/tech/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.maiagent.ai/tech/authorization-integration/vendor-integration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.