> 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/serve/web-chat-sdk/web-chat-maigpt-mode.md).

# MaiGPT モードでの埋め込み

ChatGPT ライクな MaiGPT の完全な会話インターフェースをウェブサイトや製品に埋め込み、指定コンテナとフローティング全画面の 2 種類のレイアウトに対応します

MaiGPT モードは、**ChatGPT ライクな完全な会話インターフェース**（会話履歴サイドバー、会話検索、設定パネル）を提供します。従来の「右下のチャットバブル」（floating / sidebar）とは異なり、ページのメイン機能領域や、サイト全体の AI アシスタントへの入口として適しています。

{% hint style="warning" %}
**MaiGPT モードが決定するのはインターフェースの外観だけであり、アシスタントの機能ではありません。** 適用先となる AI アシスタントの Web Chat が持つ指示、モデル、ツールがそのまま使用されます。画像生成やウェブアクセスなどの機能を利用するには、まず[MaiGPT 連携：適切なアシスタントの選択と機能の追加](/tech/ja/work/maigpt-system-integration-guide/maigpt-integration.md)に従い、アシスタントを Agent モードに設定してツールを追加してください。組織に組み込まれた MaiGPT 製品はログイン済みメンバー専用であり、その Web Chat を外部ページに埋め込むことはできません。
{% endhint %}

{% hint style="info" %}
このページでは、MaiGPT モード固有の設定を中心に説明します。埋め込みの基本概念、完全な設定リファレンス、JavaScript API については、[Web Chat 埋め込みと SDK](/tech/ja/serve/web-chat-sdk.md)を参照してください。このページに記載されていない共通パラメータ（`auth`、`queryMetadata`、ボタンの外観など）も MaiGPT モードで使用できます。
{% endhint %}

## 一、2 種類のレイアウトモード <a href="#layout-modes" id="layout-modes"></a>

同じ設定で 2 種類のレイアウトに対応し、`targetElement` の有無によって決まります：

```mermaid
flowchart TD
    A["フロントエンドで embed.min.js を読み込み<br/>maiagentChatbotConfig を設定<br/>（enabledWindowModes の先頭項目は maigpt）"] --> B{"config に<br/>targetElement がある？"}
    B -->|あり| C["モード A：指定コンテナに埋め込み<br/>iframe がコンテナの 100% × 100% を占有<br/>常時表示"]
    B -->|なし| D["モード B：右下のフローティングボタン<br/>クリック → 全画面 iframe＋右上の閉じるボタン"]
    C -.->|"selector に一致する要素がない"| E["⚠️ フォールバック：ページ全体を全画面で覆い<br/>閉じるボタンはなし"]
```

* **モード A — 指定コンテナに埋め込み**：ページ内の指定した `div` に MaiGPT を常時表示します（システムのメインワークスペースに適しています）
* **モード B — フローティングボタン + 全画面**：右下のフローティングボタンをクリックすると全画面で開きます（サイト全体の AI アシスタントへの入口に適しています）

どちらの動作も同じ `maigpt` モードによって実行され、違いは `targetElement` フィールドの有無だけです。

## 二、モード A：指定コンテナに埋め込み <a href="#mode-a-container" id="mode-a-container"></a>

### 埋め込みコード <a href="#mode-a-code" id="mode-a-code"></a>

```html
<!-- ページ内にあらかじめコンテナを用意し、サイズを設定します -->
<div id="maigpt-container" style="height: 720px;"></div>

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    primaryColor: '#1890ff',
    maigptTitle: 'Acme GPT',
  }
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>
```

{% hint style="info" %}
`baseUrl` と SDK Loader の URL は SaaS 環境（`chat.maiagent.ai`）を例にしています。プライベートクラウド／オンプレミスの場合は、お客様の環境のドメインに置き換えてください。
{% endhint %}

実際の埋め込み結果（企業ポータルサイト内に MaiGPT を埋め込み、`maigptTitle` にブランド名を設定）：

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-aab515bf01f9122d1b558aeaefcd1e59079466a0%2Fwebchat-maigpt-mode-a-container.png?alt=media" alt="MaiGPT を指定コンテナに埋め込んだ実際の画面"><figcaption><p>モード A：MaiGPT がページ内の指定コンテナに常時表示され、左側には会話履歴サイドバーがあります</p></figcaption></figure>

### コンテナの要件 <a href="#container-requirements" id="container-requirements"></a>

* **コンテナには必ず高さを設定してください**（iframe は `100%` でコンテナ全体を占有するため、コンテナの高さが 0 の場合はコンテンツが表示されません）
* `targetElement` には **CSS selector 文字列**（`'#maigpt-container'` など）または **HTMLElement オブジェクト**を指定できます
* コンテナが `position: static` の場合、SDK が自動的に `position: relative` に変更するため、通常は対応不要です
* iframe はそのコンテナ内だけを占有し、ページ内の他の領域には影響しません

{% hint style="danger" %}
**重要：selector に一致する要素がない場合、フォールバックによってページ全体が全画面で覆われ、閉じるボタンも表示されません**（console に `[maiagent] targetElement selector "..." not found, falling back to <body>` という警告が表示されます）。

次の点を確認してください：(1) selector のスペルが正しいこと、(2) SDK の読み込み時にコンテナが DOM 内に存在すること（loader の `<script>` はコンテナより後に配置し、`defer` を追加してください。SPA で動的にレンダリングされるページでは、コンテナの mount 後に SDK を読み込む必要があります）。
{% endhint %}

## 三、モード B：フローティングボタン + 全画面 <a href="#mode-b-floating" id="mode-b-floating"></a>

### 埋め込みコード <a href="#mode-b-code" id="mode-b-code"></a>

```html
<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    primaryColor: '#1890ff',
    maigptTitle: 'Acme GPT',
  }
</script>
<script
  src="https://chat.maiagent.ai/js/embed.min.js"
  defer>
</script>
```

### 動作の説明 <a href="#mode-b-behavior" id="mode-b-behavior"></a>

1. ページ右下にフローティングボタンが表示されます（色には `primaryColor` が使用されます）
2. ボタンをクリック → MaiGPT が**全画面 iframe** で開き、右上に「×」の閉じるボタンが表示されます
3. 「×」をクリック → 全画面表示が閉じ、フローティングボタンに戻ります
4. 閉じたときに iframe は非表示になるだけで、破棄されません → **再度開いたときも元の会話状態が保持されます**

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-2c2fb982ff4bef9a000a279fe72580b846b69ce3%2Fwebchat-maigpt-mode-b-demo.gif?alt=media" alt="モード B の操作デモ：フローティングボタンで全画面表示を開き、質問を送信して AI の回答を取得し、ボタンに戻します"><figcaption><p>モード B の操作デモ：フローティングボタンをクリック → 全画面で開く → 質問を送信して AI のストリーミング回答を受信 → 「×」で閉じてボタンに戻る</p></figcaption></figure>

<details>

<summary>2 つの状態の静止画</summary>

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-a605610e4f3854e4ad4134d63dd03a69e7e18b36%2Fwebchat-maigpt-mode-b-button.png?alt=media" alt="フローティングボタンの状態"><figcaption><p>閉じた状態：ページ右下にフローティングボタンだけが表示され、元のページを妨げません</p></figcaption></figure>

<figure><img src="https://605688223-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FVYMUz6J7vDZ0QTvb1rbN%2Fuploads%2Fgit-blob-51d70d15376664ce3e569f562c98e75f67ea3927%2Fwebchat-maigpt-mode-b-fullscreen.png?alt=media" alt="全画面で開いた状態"><figcaption><p>開いた状態：MaiGPT が全画面で表示され、右上の「×」で閉じることができます</p></figcaption></figure>

</details>

### ボタンの外観パラメータ（すべて任意、モード B のみ） <a href="#mode-b-button-options" id="mode-b-button-options"></a>

| パラメータ                  | デフォルト値                               | 説明                     |
| ---------------------- | ------------------------------------ | ---------------------- |
| `primaryColor`         | `#1890ff`                            | ボタンの背景色。ブランドカラーに変更できます |
| `buttonSize`           | `3rem`                               | ボタンのサイズ                |
| `buttonRadius`         | `50%`                                | ボタンの角丸                 |
| `buttonPositionBottom` | `1rem`                               | ウィンドウ下端からの距離           |
| `buttonPositionRight`  | `1rem`                               | ウィンドウ右端からの距離           |
| `buttonIcon`           | （組み込み icon）                          | カスタムボタンアイコンの画像 URL     |
| `boxShadow`            | `0.125rem 0.125rem 0.5rem #00000044` | ボタンの影                  |

## 四、完全なパラメータ一覧 <a href="#config-reference" id="config-reference"></a>

| フィールド                | 型                          | 必須 | 説明                                                                                                                                                |
| -------------------- | -------------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `webChatId`          | `string`                   | ✅  | WebChat ID                                                                                                                                        |
| `baseUrl`            | `string`                   | ✅  | Web Chat サービスの URL。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/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md)を参照してください |

未知のフィールドを設定してもエラーにはなりませんが、スペルの確認に役立つよう、console に `[maiagent] Unknown config options: ...` という警告が表示されます。

## 五、locale 言語設定 <a href="#locale" id="locale"></a>

```javascript
window.maiagentChatbotConfig = {
  // ...
  locale: 'en',
}
```

### 対応している言語設定値 <a href="#supported-locales" id="supported-locales"></a>

`zh-TW`（繁体字中国語）、`zh-CN`（簡体字中国語）、`en`、`ja`、`ko`、`th`、`vi-VN`、`id`、`fil-PH`、`ms-MY`、`km-KH`、`lo-LA`、`my-MM`

### 決定の優先順位 <a href="#locale-priority" id="locale-priority"></a>

1. config の `locale`（常に適用され、最優先です）
2. ユーザーがこのブラウザで前回使用した言語（記憶されます）
3. ブラウザの言語
4. デフォルトの `zh-TW`

{% hint style="info" %}
`locale` が影響するのは**インターフェースのテキスト**（ボタン、メニュー、メッセージ）だけであり、AI が回答する言語には影響しません。対応していない値は無視され、上記の順序でフォールバックします。
{% endhint %}

## 六、ユーザーの識別（contactId） <a href="#identify-user" id="identify-user"></a>

AI が「誰からの質問か」を認識できるようにするには（デバイスをまたいだ会話履歴の保持、パーソナライズされた回答、ユーザー権限によるツールの呼び出し）、config に `contactId` を指定する必要があります：

1. ユーザーのログイン時に、バックエンドから[連絡先の身元同期 API](/tech/ja/serve/contacts/contact-credentials-sync.md)を呼び出して `contactId` を取得します
2. フロントエンドで config に `contactId` を追加します：

```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,  // ログイン response から取得します
};
```

{% hint style="warning" %}
`contactId` には、そのログインユーザーに対応する値を指定する必要があります。`contactId` を指定しない場合は匿名での利用となります。会話履歴はブラウザ単位で保持され（同じブラウザで再読み込みしても残ります）、デバイスをまたいだ利用や、ユーザーの身元に基づく個人データへのアクセスはできません。
{% endhint %}

## 七、よくある質問 <a href="#faq" id="faq"></a>

<details>

<summary>MaiGPT モードと従来のチャットバブル（floating / sidebar）の違いは何ですか？</summary>

MaiGPT は完全な会話ワークスペース（会話履歴サイドバー、会話検索、設定パネル）であり、コンテナ全体または全画面を占有します。floating / sidebar はページの隅に重ねて表示される小さなウィンドウです。どちらも同じ `enabledWindowModes` フィールドで切り替えます：`['maigpt']` と `['floating', 'sidebar']` の違いです。MaiGPT モードではウィンドウモードの切り替えは提供されません。

</details>

<details>

<summary>会話履歴はどこに保存されますか？</summary>

WebChat の識別メカニズムに従って MaiAgent のバックエンドに保持されます。`contactId` を指定しない場合はブラウザ単位（匿名）で保持されます。`contactId` を指定した場合はその連絡先に紐付き、デバイスをまたいで利用できます。

</details>

<details>

<summary>同じページに 2 つの MaiGPT を配置できますか？</summary>

できません。SDK はページごとに一度だけ初期化され、重複する読み込みは無視されます。

</details>

<details>

<summary>SPA（React / Vue）にモード A を埋め込むにはどうすればよいですか？</summary>

コンテナ要素の mount が完了した後に `embed.min.js` を読み込んでください（または、その時点で `window.maiagentChatbotConfig` を設定し、loader script を動的に挿入してください）。コンテナが存在する前に SDK が実行されると、全画面フォールバックが発生します（[コンテナの要件](#container-requirements)を参照してください）。

</details>

<details>

<summary>左上の「MaiGPT」という名前を自社ブランドに変更できますか？</summary>

できます。config に `maigptTitle: 'Acme GPT'` を追加してください。どちらのモードにも適用されます。未設定または空文字列の場合は、デフォルトの `MaiGPT` に戻ります。

</details>


---

# 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 following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/serve/web-chat-sdk/web-chat-maigpt-mode.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.