MaiGPT モード埋め込み

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

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

本ページではMaiGPTモード専用の設定に焦点を当てています。SDKの完全な初期化フロー、イベントおよび操作コマンドについてはWeb Chat SDK 操作コマンドをご参照ください。

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

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

モード A — 指定コンテナに埋め込み：MaiGPT がページ内の指定された div に常時表示されます（システムの主要作業エリアとして適しています）
モード 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 セレクタ文字列（例：'#maigpt-container'）または HTMLElement オブジェクトを受け付けます
コンテナが position: static の場合、SDK は自動的に position: relative に変更します。通常は対応不要です
iframe は該当コンテナのみを占有し、ページの他の領域には影響しません

重要：セレクタで要素が見つからない場合、フルスクリーンでページ全体を覆うフォールバックとなり、閉じるボタンがありません（コンソールに [maiagent] targetElement selector "..." not found, falling back to <body> という警告が表示されます）。

以下をご確認ください：(1) セレクタのスペルが正しいこと；(2) SDK の読み込み時にコンテナが既に DOM に存在していること（loader の <script> はコンテナの後に配置し defer を追加してください。SPA で動的レンダリングされるページでは、コンテナがマウントされた後に 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 は非表示になるだけで破棄されません → 再度開くと元の会話状態が保持されます

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

✖

インターフェースの言語。下記の言語設定を参照。未指定の場合は前回記憶された言語またはブラウザの言語で決まります

contactId

string

✖

MaiAgent コンタクト ID。ログインユーザーの識別に使用します。ユーザー識別を参照

queryMetadata

object または string

✖

会話に付加するクエリメタデータ。詳しくはナレッジ管理権限総覧を参照

不明なフィールドを設定してもエラーにはなりませんが、コンソールに [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 を取得します
フロントエンドで contactId を config に追加します：

// ログイン後に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,  // ログインレスポンスから取得
};

contactId はそのログインユーザーに対応する値でなければなりません。contactId を指定しない場合は匿名使用となります。会話履歴はブラウザ単位で保持されます（同じブラウザでリロードしても残ります）が、デバイス間での共有やユーザー身元での個人データアクセスはできません。

七、よくある質問

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 が先に実行されてコンテナがまだ存在しない場合、フルスクリーンフォールバックがトリガーされます（コンテナの要件を参照）。

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

はい。config に maigptTitle: 'Acme GPT' を追加するだけで、両方のモードで有効になります。未設定または空文字列の場合はデフォルトの MaiGPT に戻ります。

前へWeb Chat 埋め込みと SDK

次へページ Context の注入

最終更新 21 日前

役に立ちましたか？