MaiGPT モードでの埋め込み

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

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

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

このページでは、MaiGPT モード固有の設定を中心に説明します。埋め込みの基本概念、完全な設定リファレンス、JavaScript API については、Web Chat 埋め込みと SDKを参照してください。このページに記載されていない共通パラメータ（auth、queryMetadata、ボタンの外観など）も MaiGPT モードで使用できます。

一、2 種類のレイアウトモード

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

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

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

二、モード A：指定コンテナに埋め込み

埋め込みコード

<!-- ページ内にあらかじめコンテナを用意し、サイズを設定します -->
<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>

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

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

コンテナの要件

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

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

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

三、モード B：フローティングボタン + 全画面

埋め込みコード

<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>

動作の説明

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

モード B の操作デモ：フローティングボタンで全画面表示を開き、質問を送信して AI の回答を取得し、ボタンに戻します

2 つの状態の静止画

ボタンの外観パラメータ（すべて任意、モード B のみ）

パラメータ

デフォルト値

説明

primaryColor

#1890ff

ボタンの背景色。ブランドカラーに変更できます

buttonSize

3rem

ボタンのサイズ

buttonRadius

50%

ボタンの角丸

buttonPositionBottom

1rem

ウィンドウ下端からの距離

buttonPositionRight

1rem

ウィンドウ右端からの距離

buttonIcon

（組み込み icon）

カスタムボタンアイコンの画像 URL

boxShadow

0.125rem 0.125rem 0.5rem #00000044

ボタンの影

四、完全なパラメータ一覧

フィールド

型

必須

説明

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

✖

インターフェースの言語。言語設定を参照してください。未指定の場合は、前回記憶された言語またはブラウザの言語によって決まります

contactId

string

✖

ログインユーザーを識別するための MaiAgent 連絡先 ID。ユーザーの識別を参照してください

queryMetadata

object または string

✖

会話に付加するクエリメタデータ。詳細はナレッジ管理権限の概要を参照してください

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

五、locale 言語設定

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

決定の優先順位

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

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

六、ユーザーの識別（contactId）

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

ユーザーのログイン時に、バックエンドから連絡先の身元同期 APIを呼び出して contactId を取得します
フロントエンドで config に contactId を追加します：

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

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

七、よくある質問

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

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

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

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

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

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

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

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

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

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

前へWeb Chat の埋め込みと SDK

次へページの Context の注入

最終更新 14 日前

役に立ちましたか？