ソフトウェアベンダー統合ガイド（エンドツーエンド）

ソフトウェアベンダーが Web Chat を自社プロダクトに埋め込み、権限連携を完了するためのエンドツーエンドガイド：埋め込み、一括補完、ログイン同期、Token リフレッシュ、ログアウト時の無効化

本ページは「MaiAgent Web Chat を自社プロダクトに埋め込み、自社のアカウントシステムと権限連携を行う」ソフトウェアベンダー向けです。ユーザーがお客様のシステムにログインすると、AI アシスタントがそのユーザーを認識し、会話履歴を遡ることができ、そのユーザーの権限でお客様のシステムの API を呼び出せるようになります。

連携の旅は全5段階で構成されています。本ページでは各段階で何をするか、どの順序で進めるかを説明し、詳細はそれぞれの技術ドキュメントへリンクしています。

連携の全体像

核心的なコンセプトは1つだけです：連絡先（Contact）——お客様のシステムの各ユーザーが、MaiAgent の1つの連絡先に対応します。連絡先には会話履歴、パーソナライズ属性、ナレッジベースのクエリ範囲、ツール認証情報が紐付けられます。権限連携のすべてのアクションは、本質的には「お客様のユーザー ↔ 連絡先」という対応関係とその認証情報を維持することです。コンセプトの紹介は連絡先（Contact）の紹介と連携を参照してください。

フロントエンドとバックエンドの役割分担

連携の全工程において、お客様のフロントエンドは「チャットウィンドウの読み込み」のみを担当し、Token や API Key を伴うすべての呼び出しはお客様のバックエンドから発信します：

このうち setup-contact-credentials は API Key 不要（公開エンドポイント）です。bulk-import、PATCH、DELETE はすべて Authorization: Api-Key 認証が必要であり、バックエンドからのみ呼び出せます。

ステップ1：Web Chat を埋め込む

プロダクトの形態に応じて埋め込み方法を選択してください。どちらも同じ SDK と同じ連絡先の仕組みを使用しています：

形態	適したケース	ドキュメント
チャットバブル（floating／sidebar）	カスタマーサポート、問い合わせなどの補助機能	Web Chat 埋め込みと SDK
MaiGPT モード（ChatGPT ライクなフルインターフェース）	ページのメイン機能エリア、サイト全体の AI 入口	MaiGPT モード埋め込み

ID 連携を行う Web Chat には、この時点で「許可された埋め込みドメイン」リストを設定することを推奨します（現在 MaiAgent チームがお客様のために設定します。ドメインリストを担当窓口にご提供ください）。ID 同期 API を呼び出せるソースを制限できます。許可された埋め込みドメインを参照してください。

ステップ2：初回連携——既存ユーザーの一括補完

既存システムの初回連携時に、現在のユーザーの連絡先を一括で補完します。2つの方法があります：

方法	適したケース	ドキュメント
Excel 一括インポート（POST /contacts/bulk-import/）	大量のユーザー（1回あたり上限 10,000 行）。ナレッジクエリ範囲と API ツール認証情報も同時に取り込めます	連絡先の一括インポート
身元同期 API を1件ずつ呼び出し	ログインフローに沿って段階的に補完する場合、または少量の場合	既存ユーザーの一括補完

補完時点でユーザーの Access Token が取得できなくても問題ありません。まず対応関係を作成し、Token 認証情報はステップ4のログインフローで各ユーザーの次回ログイン時に補完します。

ステップ3：ユーザー新規追加時に連絡先を作成

補完が完了したら、お客様のシステムの「アカウント作成」フローに API 呼び出しを1回追加します。新規ユーザーが登録された時点で対応する連絡先を作成します：

• バックエンドで身元同期 API（setup-contact-credentials）を呼び出し、お客様のシステムのユーザー識別子を sourceId として指定します

• 返却された contactId を会員データテーブルに保存します（推奨されるフィールド設計はログインフローの統合箇所を参照してください）

sourceId は冪等キーです。同一の sourceId で重複呼び出ししても更新のみで、重複作成されません。そのため、このステップはステップ2およびステップ4と安全に共存できます。

ステップ4：ログインと Token リフレッシュ

毎回ログイン成功後、Access Token を生成してから、バックエンドで同じ身元同期 API をもう1回呼び出し、新しい Token（mcpCredentials）を渡します。これにより AI アシスタントがそのユーザーの身元と権限でお客様のシステムの API を呼び出せるようになります。Token リフレッシュ時も同じ方法です。もう1回呼び出すだけで、同一の（連絡先、ツール）の組み合わせでは更新となり、重複作成されません。完全なシーケンス図と注意事項（非同期呼び出し、失敗時にログインをブロックしない）は連絡先の身元同期と Token 更新を参照してください。

フロントエンドでは、ページで Web Chat を初期化する際に contactId を指定します。ユーザーの識別を参照してください。

AI にお客様のシステムの API を呼び出させる必要がなく、ユーザーを識別するだけでよい場合は、バックエンドを経由せず、フロントエンドの config に auth を指定するだけで対応できます。選択の基準についてはフロントエンド auth とバックエンド連携の選び方を参照してください。

ステップ5：ログアウトと認証情報の無効化

ログアウト時には2つの処理があり、作用範囲が異なるため、両方実施することを推奨します：

• フロントエンド：SDK の signOut() を呼び出し、チャットウィンドウを匿名状態に戻します

• バックエンド：該当連絡先のツール認証情報を削除し、AI が即座にそのユーザーの身元でツールを呼び出せないようにします

詳細な API と両者の違いの対照表はログアウトと認証情報の無効化を参照してください。

連携チェックリスト

段階	アクション	ドキュメント
構築	Web Chat を埋め込む（通常または MaiGPT モード）	Web Chat 埋め込みと SDK／MaiGPT モード
構築	ドメインリストを MaiAgent に提供し「許可された埋め込みドメイン」を設定	許可された埋め込みドメイン
構築	会員データテーブルに maiagent_contact_id フィールドを追加	ログインフローの統合箇所
構築	既存ユーザーを一括補完	連絡先の一括インポート
運用	アカウント作成フローで身元同期 API を呼び出し	連絡先の身元同期と Token 更新
運用	ログイン／Token リフレッシュフローで認証情報を更新	呼び出しタイミング
運用	ログアウトフローで認証情報を無効化	ログアウトと認証情報の無効化
高度	部門、会員ランクなどのパーソナライズ属性を同期	連絡先情報の同期
高度	クエリメタデータで各ユーザーのナレッジベース検索範囲を制限	ナレッジ管理権限（Query Metadata）