> 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/ja/authorization-integration/vendor-integration-guide.md). # ソフトウェアベンダー連携ガイド（エンドツーエンド） ソフトウェアベンダーが Web Chat を自社製品に組み込み、権限連携を完了するためのエンドツーエンドガイド：組み込み、一括補完、ログイン同期、Token の更新、ログアウト時の失効 このページは、MaiAgent Web Chat を自社製品に組み込み、自社のアカウントシステムと権限を連携するソフトウェアベンダー向けです。ユーザーが自社システムにログインすると、AI アシスタントがユーザーを識別し、会話履歴を参照して、**そのユーザーの権限**で自社システムの API を呼び出せるようになります。 統合プロセスは5つの段階で構成されます。このページでは、各段階で行うことと実施順序を説明し、詳細については対応する技術ドキュメントへのリンクを示します。 ## 統合の全体像 ```mermaid flowchart LR subgraph ONCE["初回のみの構築"] A["Web Chat を組み込む"] --> B["既存ユーザーを一括で補完する"] end subgraph DAILY["日常運用（アカウントのライフサイクル）"] C["ユーザー追加時に連絡先を作成する"] --> D["ログイン時に Token を更新する"] D --> E["Token 更新時に再度同期する"] E --> F["ログアウト時に認証情報を失効させる"] end ONCE --> DAILY ``` 中心となる概念は **連絡先（Contact）** の1つだけです。自社システムの各ユーザーは、MaiAgent の1件の連絡先に対応します。連絡先には、会話履歴、パーソナライズ属性、ナレッジベースの検索範囲、ツールの認証情報が紐づきます。権限連携のすべての操作は、実質的に「自社のユーザー ↔ 連絡先」という対応関係と、その認証情報を維持するものです。概念については、[連絡先（Contact）の概要と連携](/tech/ja/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` 認証が必要であり、バックエンドからのみ呼び出せます。 ## ステップ1：Web Chat を組み込む 製品の形態に応じて組み込み方法を選択してください。どちらも同じ SDK と連絡先の仕組みを使用します。 | 形態 | 適した用途 | ドキュメント | | ----------------------------------- | ------------------------------ | -------------------------------------------------------------------------------- | | チャットバブル（floating／sidebar） | カスタマーサポートや相談などの補助機能 | [Web Chat の組み込みと SDK](/tech/ja/api-integration/web-chat-sdk.md) | | MaiGPT モード（ChatGPT のような完全なインターフェース） | ページの主要機能領域、サイト全体の AI エントリーポイント | [MaiGPT モードの組み込み](/tech/ja/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | {% hint style="info" %} ID 連携を行う Web Chat では、この時点で「組み込みを許可するドメイン」リストを設定することを推奨します。現在は MaiAgent チームが設定するため、連携窓口にドメインリストを提供してください。これにより、ID 同期 API を呼び出せるオリジンを限定できます。詳しくは、[組み込みを許可するドメイン](/tech/ja/api-integration/web-chat-sdk.md#embed-origin-allowlist)を参照してください。 {% endhint %} ## ステップ2：初回統合—既存ユーザーを一括で補完する 既存システムを初めて連携する場合は、まず既存ユーザーに対応する連絡先を一括で作成します。次の2つの方法があります。 | 方法 | 適した用途 | ドキュメント | | ------------------------------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------- | | **Excel 一括インポート**（`POST /contacts/bulk-import/`） | 大量のユーザー（1回につき最大10,000行）。ナレッジ検索範囲と API ツールの認証情報も同時に登録可能 | [連絡先の一括インポート](/tech/ja/authorization-integration/contacts.md#bulk-import) | | **ユーザーごとに ID 同期 API を呼び出す** | ログインフローに沿って段階的に補完する場合、またはユーザー数が少ない場合 | [既存ユーザーの一括補完](/tech/ja/authorization-integration/contact-credentials-sync.md#backfill) | 補完時にユーザーの Access Token を取得できなくても問題ありません。まず対応関係を作成してください。Token の認証情報は、各ユーザーが次回ログインした際に、ステップ4のログインフローで追加されます。 ## ステップ3：ユーザー追加時に連絡先を作成する 補完が完了したら、自社システムのアカウント作成フローに API 呼び出しを1回追加し、新規ユーザーが最初から対応する連絡先を持つようにします。 * バックエンドから [ID 同期 API（`setup-contact-credentials`）](/tech/ja/authorization-integration/contact-credentials-sync.md)を呼び出し、自社システムのユーザー識別子を `sourceId` として使用します。 * 返された `contactId` を会員データベースに保存します。推奨フィールド設計については、[ログインフローへの組み込み位置](/tech/ja/authorization-integration/contact-credentials-sync.md#login-flow)を参照してください。 `sourceId` は冪等キーです。同じ `sourceId` で繰り返し呼び出しても更新されるだけで、重複して作成されません。そのため、このステップはステップ2およびステップ4と安全に併用できます。 ## ステップ4：ログインと Token の更新 ログインに成功して Access Token が発行されるたびに、バックエンドから同じ ID 同期 API を再度呼び出し、**新しい Token**（`mcpCredentials`）を渡します。これにより、AI アシスタントはそのユーザーの ID と権限を使用して自社システムの API を呼び出せます。Token の更新時も同じ方法で、もう一度呼び出すだけです。同じ連絡先とツールの組み合わせは重複作成されず、更新されます。完全なシーケンス図と注意事項（非同期で呼び出し、失敗してもログインを妨げないこと）については、[連絡先の ID 同期と Token の更新](/tech/ja/authorization-integration/contact-credentials-sync.md)を参照してください。 フロントエンドでは、ページ上で Web Chat を初期化する際に `contactId` を指定します。詳しくは、[ユーザーの識別](/tech/ja/api-integration/web-chat-sdk.md#identify-users)を参照してください。 {% hint style="info" %} AI が自社システムの API を呼び出す必要がなく、ユーザーを識別するだけでよい場合は、バックエンドを経由せず、フロントエンドの config に `auth` を指定することもできます。選択時の考慮事項については、[フロントエンドの auth とバックエンド連携の選び方](/tech/ja/authorization-integration/contact-credentials-sync.md#frontend-vs-backend)を参照してください。 {% endhint %} ## ステップ5：ログアウトと認証情報の失効 ログアウト時には、作用範囲が異なる次の2つの処理を行うことを推奨します。 * **フロントエンド**：SDK の `signOut()` を呼び出し、チャットウィンドウを匿名状態に戻します。 * **バックエンド**：該当する連絡先のツール認証情報を削除し、AI がそのユーザーの ID でツールを呼び出せないようにします。 詳細な API と両者の違いについては、[ログアウトと認証情報の失効](/tech/ja/authorization-integration/contact-credentials-sync.md#logout-revoke)を参照してください。 ## 統合チェックリスト | 段階 | 操作 | ドキュメント | | -- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | 構築 | Web Chat（通常モードまたは MaiGPT モード）を組み込む | [Web Chat の組み込みと SDK](/tech/ja/api-integration/web-chat-sdk.md)／[MaiGPT モード](/tech/ja/api-integration/web-chat-sdk/web-chat-maigpt-mode.md) | | 構築 | MaiAgent が「組み込みを許可するドメイン」を設定できるようにドメインリストを提供する | [組み込みを許可するドメイン](/tech/ja/api-integration/web-chat-sdk.md#embed-origin-allowlist) | | 構築 | 会員データベースに `maiagent_contact_id` フィールドを追加する | [ログインフローへの組み込み位置](/tech/ja/authorization-integration/contact-credentials-sync.md#login-flow) | | 構築 | 既存ユーザーを一括で補完する | [連絡先の一括インポート](/tech/ja/authorization-integration/contacts.md#bulk-import) | | 運用 | アカウント作成フローで ID 同期 API を呼び出す | [連絡先の ID 同期と Token の更新](/tech/ja/authorization-integration/contact-credentials-sync.md) | | 運用 | ログイン／Token 更新フローで認証情報を更新する | [呼び出すタイミング](/tech/ja/authorization-integration/contact-credentials-sync.md#when-to-call) | | 運用 | ログアウトフローで認証情報を失効させる | [ログアウトと認証情報の失効](/tech/ja/authorization-integration/contact-credentials-sync.md#logout-revoke) | | 高度 | 部門や会員ランクなどのパーソナライズ属性を同期する | [連絡先データの同期](/tech/ja/authorization-integration/contact-credentials-sync.md#sync-contact-profile) | | 高度 | Query Metadata を使用してユーザーごとのナレッジベース検索範囲を制限する | [ナレッジ管理権限（Query Metadata）](/tech/ja/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/ja/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.