> 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/api-integration/web-chat-sdk/web-chat-maigpt-mode.md). # MaiGPT モード埋め込み MaiGPT モードは**ChatGPTライクな完全な対話インターフェース**（サイドバー会話履歴、会話検索、設定パネル）を提供します。既存の「右下チャットバブル」（floating / sidebar）とは異なり、ページの主要機能エリアや全サイトAIアシスタントの入口として適しています。 {% hint style="info" %} 本ページではMaiGPTモード専用の設定に焦点を当てています。SDKの完全な初期化フロー、イベントおよび操作コマンドについては[Web Chat SDK 操作コマンド](/tech/ja/api-integration/web-chat-sdk.md)をご参照ください。 {% endhint %} ## 一、2つのレイアウトモード 同一の設定で2つのレイアウトに対応しており、`targetElement` の有無によって決まります： ```mermaid flowchart TD A["フロントエンドで embed.min.js を読み込み
maiagentChatbotConfig を設定
（enabledWindowModes の最初の項目が maigpt）"] --> B{"config に
targetElement がある？"} B -->|あり| C["モード A：指定コンテナに埋め込み
iframe がコンテナを 100% × 100% で満たす
常時表示"] B -->|なし| D["モード B：右下フローティングボタン
クリック → フルスクリーン iframe＋右上閉じるボタン"] C -.->|"セレクタで要素が見つからない"| E["⚠️ フォールバック：フルスクリーンでページ全体を覆う
閉じるボタンなし"] ``` * **モード A — 指定コンテナに埋め込み**：MaiGPT がページ内の指定された `div` に常時表示されます（システムの主要作業エリアとして適しています） * **モード B — フローティングボタン + フルスクリーン**：右下のフローティングボタンをクリックするとフルスクリーンで開きます（全サイトAIアシスタントの入口として適しています） どちらの動作も同じ `maigpt` モードによってトリガーされ、違いは `targetElement` フィールドの有無のみです。 ## 二、モード A：指定コンテナに埋め込み ### 埋め込みコード ```html
``` {% hint style="info" %} `baseUrl` と SDK Loader の URL は SaaS 環境（`chat.maiagent.ai`）を例としています。プライベートクラウド／オンプレミスデプロイの場合は、お使いの環境のドメインに変更してください。 {% endhint %} 実際の埋め込み効果（企業ポータルサイトに MaiGPT を埋め込み、`maigptTitle` をブランド名に設定）： ### コンテナの要件 * **コンテナには高さを指定する必要があります**（iframe は `100%` でコンテナを満たします。コンテナの高さが 0 の場合、コンテンツが表示されません） * `targetElement` は **CSS セレクタ文字列**（例：`'#maigpt-container'`）または **HTMLElement オブジェクト**を受け付けます * コンテナが `position: static` の場合、SDK は自動的に `position: relative` に変更します。通常は対応不要です * iframe は該当コンテナのみを占有し、ページの他の領域には影響しません {% hint style="danger" %} **重要：セレクタで要素が見つからない場合、フルスクリーンでページ全体を覆うフォールバックとなり、閉じるボタンがありません**（コンソールに `[maiagent] targetElement selector "..." not found, falling back to ` という警告が表示されます）。 以下をご確認ください：(1) セレクタのスペルが正しいこと；(2) SDK の読み込み時にコンテナが既に DOM に存在していること（loader の ` ``` ### 動作の説明 1. ページ右下にフローティングボタンが表示されます（色は `primaryColor` に従います） 2. ボタンをクリック → MaiGPT が**フルスクリーン iframe** で開き、右上に「×」閉じるボタンが表示されます 3. 「×」をクリック → フルスクリーンが折りたたまれ、フローティングボタンに戻ります 4. 折りたたみ時に iframe は非表示になるだけで破棄されません → **再度開くと元の会話状態が保持されます**
2つの状態の静的スクリーンショット
### ボタン外観パラメータ（すべて任意、モード B のみ適用） | パラメータ | デフォルト値 | 説明 | | ---------------------- | ------------------------------------ | -------------------- | | `primaryColor` | `#1890ff` | ボタンの背景色。ブランドカラーに変更可能 | | `buttonSize` | `3rem` | ボタンのサイズ | | `buttonRadius` | `50%` | ボタンの角丸 | | `buttonPositionBottom` | `1rem` | ビューポート下端からの距離 | | `buttonPositionRight` | `1rem` | ビューポート右端からの距離 | | `buttonIcon` | （内蔵アイコン） | カスタムボタンアイコンの画像 URL | | `boxShadow` | `0.125rem 0.125rem 0.5rem #00000044` | ボタンの影 | ## 四、完全パラメータ一覧 | フィールド | 型 | 必須 | 説明 | | -------------------- | -------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `webChatId` | `string` | ✅ | WebChat ID | | `baseUrl` | `string` | ✅ | Web Chat サービスアドレス。SaaS の場合は `https://chat.maiagent.ai/web-chats` | | `enabledWindowModes` | `string[]` | ✅ | 固定で `['maigpt']`（最初の要素がモードを決定します） | | `targetElement` | `string` または `HTMLElement` | ✖ | 値あり → モード A、値なし → モード B | | `maigptTitle` | `string` | ✖ | サイドバー左上のブランドタイトル。未設定の場合は `MaiGPT` が表示されます | | `primaryColor` | `string` | ✖ | インターフェースのメインカラー。ブランドカラーに調整可能 | | `locale` | `string` | ✖ | インターフェースの言語。下記の[言語設定](#locale)を参照。未指定の場合は前回記憶された言語またはブラウザの言語で決まります | | `contactId` | `string` | ✖ | MaiAgent コンタクト ID。ログインユーザーの識別に使用します。[ユーザー識別](#identify-user)を参照 | | `queryMetadata` | `object` または `string` | ✖ | 会話に付加するクエリメタデータ。詳しくは[ナレッジ管理権限総覧](/tech/ja/authorization-integration/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)を参照 | 不明なフィールドを設定してもエラーにはなりませんが、コンソールに `[maiagent] Unknown config options: ...` という警告が表示され、スペルチェックに役立ちます。 ## 五、locale 言語設定 ```javascript window.maiagentChatbotConfig = { // ... locale: 'en', } ``` ### 対応する言語値 `zh-TW`（繁体中国語）、`zh-CN`（簡体中国語）、`en`、`ja`、`ko`、`th`、`vi-VN`、`id`、`fil-PH`、`ms-MY`、`km-KH`、`lo-LA`、`my-MM` ### 決定順序 1. config の `locale`（必ず適用され、最も優先度が高い） 2. ユーザーがこのブラウザで前回使用した言語（記憶されます） 3. ブラウザの言語 4. デフォルト `zh-TW` {% hint style="info" %} `locale` は**インターフェースのテキスト**（ボタン、メニュー、プロンプト）にのみ影響し、AIの回答言語には影響しません。サポートされていない値を指定した場合は無視され、順番にフォールバックします。 {% endhint %} ## 六、ユーザー識別（contactId） AIに「誰が質問しているか」を知らせたい場合（デバイス間で会話履歴を保持、パーソナライズされた回答、ユーザー権限でのツール呼び出し）、config に `contactId` を設定する必要があります： 1. バックエンドでユーザーログイン時に[コンタクト認証同期 API](/tech/ja/authorization-integration/contact-credentials-sync.md)を呼び出して `contactId` を取得します 2. フロントエンドで `contactId` を config に追加します： ```javascript // ログイン後にAPIからユーザー情報（contactIdを含む）を取得した想定 const loginResponse = await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify({ username, password }) }); const userData = await loginResponse.json(); // WebChat configを動的に設定 window.maiagentChatbotConfig = { webChatId: 'your-web-chat-id', baseUrl: 'https://chat.maiagent.ai/web-chats', enabledWindowModes: ['maigpt'], targetElement: '#maigpt-container', contactId: userData.maiagentContactId, // ログインレスポンスから取得 }; ``` {% hint style="warning" %} `contactId` はそのログインユーザーに対応する値でなければなりません。`contactId` を指定しない場合は匿名使用となります。会話履歴はブラウザ単位で保持されます（同じブラウザでリロードしても残ります）が、デバイス間での共有やユーザー身元での個人データアクセスはできません。 {% endhint %} ## 七、よくある質問
MaiGPT モードと従来のチャットバブル（floating / sidebar）の違いは何ですか？ MaiGPT は完全な対話ワークインターフェース（サイドバー会話履歴、会話検索、設定パネル）であり、コンテナ全体またはフルスクリーンを占有します。floating / sidebar はページの隅に重ねて表示される小さなウィンドウです。どちらも同じ `enabledWindowModes` フィールドで切り替えます：`['maigpt']` vs `['floating', 'sidebar']`。MaiGPT モードではウィンドウモードの切り替えは提供されません。
会話履歴はどこに保存されますか？ WebChat の識別メカニズムに基づいて MaiAgent バックエンドに保存されます。`contactId` を指定しない場合はブラウザ単位（匿名）で保存されます。`contactId` を指定した場合はそのコンタクトに紐づき、デバイス間で共有できます。
同じページに2つの MaiGPT を配置できますか？ できません。SDK はページごとに1回のみ初期化され、重複した読み込みは無視されます。
SPA（React / Vue）でモード A を埋め込むにはどうすればよいですか？ コンテナ要素のマウントが完了してから `embed.min.js` を読み込んでください（またはその時点で `window.maiagentChatbotConfig` を設定し、loader script を動的に挿入してください）。SDK が先に実行されてコンテナがまだ存在しない場合、フルスクリーンフォールバックがトリガーされます（[コンテナの要件](#container-requirements)を参照）。
左上の「MaiGPT」の名前を自社ブランドに変更できますか？ はい。config に `maigptTitle: 'Acme GPT'` を追加するだけで、両方のモードで有効になります。未設定または空文字列の場合はデフォルトの `MaiGPT` に戻ります。
--- # 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/api-integration/web-chat-sdk/web-chat-maigpt-mode.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.