Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Web Chat の埋め込みと SDK

MaiAgent Web Chat をあらゆるウェブサイトに埋め込むための、埋め込みコード、ウィンドウモード、ユーザー識別、設定の完全リファレンス、JavaScript SDK API

ウェブページに埋め込みコードを追加するだけで、MaiAgent の AI Agent をウェブサイトに組み込めます。埋め込みコードが embed.min.js（以下、SDK）を読み込むと、SDK はページ上にチャットボタンと iframe のチャットウィンドウを作成し、プログラムから操作できるグローバルな MaiAgent JavaScript API を提供します。

このページは、Web Chat の埋め込みに関する完全な技術リファレンスです。関連するトピックは次のとおりです。

1. クイックスタート

ページの </body> の前に次のコードを追加します。

<script>
  window.maiagentChatbotConfig = {
    webChatId: 'your-web-chat-id',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    primaryColor: '#1890ff',
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

  • webChatId は管理画面の Web Chat 設定ページで取得します（会話プラットフォームとの連携：ウェブサイトを参照してください。管理画面で生成する埋め込みコードには自動で設定されます）

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

  • window.maiagentChatbotConfig は必ず SDK スクリプトの読み込み前に定義してください

デフォルトでは、ページの右下にチャットボタンが表示されます。クリックするとフローティングチャットウィンドウが開き、ユーザーは floating と sidebar の2つのウィンドウモードを切り替えられます。

初期化のタイミング

SDK は読み込み後に document.body.onload ハンドラーを登録して初期化します。通常、手動操作は不要です。初期化のタイミングを制御したい場合（SPA でコンテナのマウントを待つ場合や、描画を遅延させる場合など）は、次の方法を使用します。

  1. スクリプトを遅延読み込みする：適切なタイミングで embed.min.js の <script> タグを動的に挿入します

  2. 手動で実行する：window.maiagentChatbotConfig を設定してから document.body.onload() を呼び出します

同じページでの SDK の初期化は1回のみです。重複した読み込みは無視されます。

2. ウィンドウモード

enabledWindowModes 配列で、ユーザーが利用できるウィンドウモードを指定します。最初の要素がデフォルトのモードです。未設定の場合は ['floating', 'sidebar'] と同じになります。

モード
レイアウト
利用場面

floating

ページ右下に重なるフローティングウィンドウです。ボタンをドラッグでき、ウィンドウサイズを変更できます（320×400～900×900 px）

一般的なカスタマーサポートや問い合わせ対応に適しています

sidebar

ブラウザーウィンドウの右端に沿うサイドバーです（幅320～800 px、ドラッグで調整可能）。ページコンテンツは自動的に縮小してスペースを確保します

ページを見ながら会話する作業に適しています

inline

指定したコンテナ（container）内にチャットウィンドウを直接配置します。コンテナの幅と高さを満たして常時表示され、チャットボタンはありません

カスタマーサポートセンターのページや製品ページのサイドバーなど、ページ内に固定の会話エリアを設ける場合に適しています

maigpt

ChatGPT のような完全なインターフェース（会話履歴サイドバー、検索、設定）です。指定したコンテナまたは全画面を満たします

ページのメイン機能エリアやサイト全体の AI 入口に適しています。MaiGPT モードを参照してください

  • 配列に2つ以上のモードがある場合、チャットウィンドウにモード切り替えボタンが表示されます。allowWindowModeSwitch: false で非表示にできます

  • 最初の要素が maigpt の場合は MaiGPT モードになり、ほかの要素は無効です（このモードでは切り替えを提供しません）

  • inline は単独で使用してください（enabledWindowModes: ['inline']）。floating や sidebar と同じ配列に入れると埋め込みは行われず、コンソールにエラーが表示されます

  • 旧フィールド defaultWindowMode は非推奨です。引き続き動作します（enabledWindowModes: [その値] として扱われます）が、コンソールに非推奨の警告が表示されます

inline モードのコンテナ

inline モードでは、container で埋め込み先を指定します。コンテナの高さは自分で設定してください（チャットウィンドウの最小高さは400 pxです）。

container の指定方法

動作

CSS セレクター文字列（例：'#chat-container'）

要素の出現を最大5秒待ちます

HTMLElement、または { element }

直接使用します。要素はすでにページに接続されている必要があります

{ selector, waitForElement, waitTimeout }

waitForElement: false で待機を無効にします。waitTimeout で待機時間をミリ秒単位で調整できます（デフォルトは5000）

  • container が未設定、セレクターが誤っている、または要素が待機時間内に出現しない場合、チャットウィンドウは表示されず、コンソールに理由が表示されます

  • コンテナが position: static の場合、SDK は position: relative に変更します

  • inline モードは常時表示され、開閉はできません。MaiAgent.control.open()／close() は作用しません

floating、sidebar、maigpt の画面例

floating モード：チャットウィンドウがページ右下に重なって表示されます
floating：チャットウィンドウがページ右下に重なり、ページのレイアウトに影響しません。ボタンをドラッグして位置を移動できます
sidebar モード：チャットウィンドウが右端に沿って表示され、ページコンテンツが自動的に縮小します
sidebar：チャットウィンドウがブラウザーウィンドウの右端に沿って表示され、ページコンテンツが自動的に縮小してスペースを確保します。ページを見ながら会話する場合に適しています
maigpt モード：ChatGPT のような完全な会話インターフェースです
maigpt：会話履歴サイドバーを含む、ChatGPT のような完全なインターフェースです。詳細はMaiGPT モードでの埋め込みを参照してください

3. ユーザーの識別

Web Chat には、連絡先（Contact）が紐付けられているかどうかに応じて、3つのIDレベルがあります。

レベル
設定方法
会話履歴
AI のパーソナライズ／ユーザー権限でのツール呼び出し

匿名

設定しません

ブラウザー単位で保持します

✖

フロントエンド auth

config に auth: { sourceId, ... } を指定すると、SDK が連絡先を自動で作成または照合します

連絡先に紐付き、デバイス間で共有できます

✔

バックエンド連携

バックエンドでID同期 APIを呼び出して contactId を取得し、config に contactId を指定します

連絡先に紐付き、デバイス間で共有できます

✔

フロントエンド auth：SDK は初期化完了後に、auth の内容を使って MaiAgent のID同期 API（setup-contact-credentials）を自動的に呼び出し、sourceId に基づいて連絡先を作成または照合します。

getToken（または静的な accessToken＋organizationId）は、組織に標準搭載された MaiGPT を組織メンバー向けに埋め込む場合にのみ使用します。この場合、sourceId はメンバーのユーザー ID である必要があります。全体の手順はメンバーIDでの埋め込みを参照してください。一般の顧客や訪問者の識別には、これらのフィールドは不要です。

Web Chat のログイン設定で「埋め込み側から Source ID を使ってログインせずに会話することを許可する」を有効にし、署名モードを選択した場合、ts と sig は必須です。未指定または検証に失敗した場合、ユーザーはログインページにリダイレクトされます。MaiAgent.auth.setup() を手動で呼び出す場合も、この2つのフィールドを指定できます。

バックエンド連携：ユーザーのログイン時に、バックエンドから同じ API を呼び出します（MCP ツールの認証情報も同時に紐付けられます）。返された contactId を会員データに保存し、フロントエンドには contactId のみを渡します。

2つの方法は、次の基準で選択します。

  • 「ユーザーを識別し、デバイス間で会話を保持する」だけでよい場合 → フロントエンド auth が最も簡単です

  • ユーザーの Access Token を MCP ツールの認証情報に紐付ける必要があり（AI がユーザー権限で API を呼び出すため）、フロントエンドのページソースに token を含めたくない場合 → バックエンド連携を使用します

  • どちらも同じ連絡先の仕組みを使用します。同じ sourceId は同じ連絡先として扱われるため、併用できます

queryMetadata を使用して、ユーザーのナレッジベース検索範囲を制御することもできます（RAG の権限フィルタリング）。詳細はナレッジ管理の権限（Query Metadata）の概要を参照してください。queryMetadata は LLM prompt に入りません。AI に値を認識させたい場合は contextData を使用してください。

セキュリティ上の注意事項

contactId はID認証情報です。これを取得した人は、そのユーザーとして会話し、会話履歴を閲覧できます。contactId はログイン後のページで、そのユーザー本人にのみ出力してください。公開ページのソースコードに含めないでください。

auth.sourceId の要件は、署名検証を有効にしているかどうかで異なります。

  • 署名検証が無効の場合：ID同期は公開エンドポイントです。推測できる sourceId は、なりすましに利用できます。UUID などの推測できない値を使用し、連番、Email、電話番号は使用しないでください。

  • 署名検証が有効の場合：安全性は sourceId 自体ではなく署名によって確保されます。そのため、学籍番号、社員番号、登録済み Email などの読みやすい値をそのまま使用できます。秘密鍵はサーバーにのみ保存され、秘密鍵がなければ sourceId を知っていても有効な署名を計算できません。

署名検証

Web Chat のログイン設定で「埋め込み側から Source ID を使ってログインせずに会話することを許可する」を有効にすると、ウェブサイトにログイン済みのユーザーはチャットウィンドウで再度ログインする必要がなくなります。設定のスイッチ、秘密鍵、署名の有効期間、検証失敗ログは、管理画面のログイン設定タブにあります。操作方法はユーザーマニュアルの連絡先の Source ID を使用したログイン不要の会話を参照してください。

検証方式は2種類あり、署名モードを推奨します。

検証方式
動作

署名検証を必須にする

ts と sig が必要です。署名検証に成功した場合のみアクセスを許可します

Source ID のみ

署名は検証せず、sourceId があればアクセスを許可します。テストや閉じた社内ネットワーク環境での利用にのみ適しています

署名アルゴリズム

小文字の hex 文字列として渡します。ts は Unix 秒（UTC）です。秘密鍵は管理画面でプラットフォームが生成します。サーバーの環境変数にのみ保存し、フロントエンドのコードに記述しないでください。

フロントエンドで署名を渡す方法

バックエンドで計算した ts と sig を、sourceId とともに SDK に渡します。ページの読み込み時点でユーザーが判明している場合は config の auth に設定します。SPA でログイン後に署名を取得する場合は、MaiAgent.auth.setup() を呼び出します。

管理画面の「連携サンプル」が生成したフロントエンドのサンプルに setupAuth がある場合は、auth.setup に変更してください。SDK は setupAuth メソッドを公開していないため、そのまま貼り付けるとブラウザーで TypeError が発生します。

検証ルール

ルール
説明

有効期間

管理画面で1／5／15分に設定できます。デフォルトは5分です

時刻の許容範囲

60秒のずれを許容します。未来に60秒を超えるタイムスタンプはすべて拒否します

1回限り

同じ署名で成功できるのは1回のみです。署名自体がリプレイ防止の nonce として機能します

プラットフォームへの紐付け

署名には webChatId が含まれるため、同じ組織の別の Web Chat の署名は再利用できません

拒否時の応答

すべての失敗理由に対して外部への応答は同一です。理由や sourceId の存在有無を開示しません

署名は1回のみ有効です。アクセスのたびに再計算し、キャッシュしないでください。有効期間は「この署名を連絡先のIDに交換できる時間」を制限するものであり、会話の継続時間ではありません。IDを取得した後は、署名が期限切れになっても会話は中断されません。

有効期間とログアウトの関係

取得した contactId 自体には有効期限がなく、現在、プラットフォームにはこれを無効にするエンドポイントもありません。ユーザーがウェブサイトからログアウトした後に制御できるのは、新しい署名の発行を停止することです。フロントエンドで MaiAgent.auth.signOut() を呼び出すと、チャットウィンドウを匿名状態に戻せます。ツール認証情報の失効については、ログアウトと認証情報の失効を参照してください。

署名検証失敗の調査

管理画面のログイン設定にある「署名検証失敗ログの表示」には、最近の失敗イベントと理由が表示されます。各理由の一般的な原因は、ユーザーマニュアルの署名検証失敗ログを参照してください。最も多い「署名不一致」は、通常、秘密鍵の不一致または署名文字列の組み立て方の誤りが原因です（区切り文字は半角のピリオドです）。

埋め込みを許可するドメイン

会話プラットフォームの管理者は、管理画面の 基本設定 → 埋め込みを許可するドメイン でリストを設定できます。操作手順はユーザーマニュアルの埋め込みを許可するドメインを参照してください。リストが空でない場合、次の2つを同時に制限します。

  • 埋め込み：リストに含まれないウェブサイトでの埋め込みをブラウザーがブロックします。

  • ID同期：auth と setup-contact-credentials の両方でオリジンの照合が必要です。サーバー間の呼び出しにはブラウザーの Origin ヘッダーがないため、body に embedOrigin を指定してください。連絡先のID同期と Token の更新を参照してください。

照合ルールは次のとおりです。

リストの状態
動作

空のリスト（デフォルト）

オリジンを制限しません

https://example.com を指定

scheme＋host（＋port）を完全一致で照合します

*.example.com を指定

example.com とそのすべてのサブドメインを対象にします（scheme／port は問いません）

値はあるものの、すべて形式が無効

すべてのオリジンを拒否します（fail closed）。制限なしに自動で戻ることはありません

外部サイトに埋め込み、ID機能を使用する Web Chat では、contactId を取得できるオリジンを絞るため、このリストを設定することを推奨します。

4. 設定オプションのリファレンス

window.maiagentChatbotConfig がサポートするすべてのフィールドです。未知のフィールドを指定してもエラーにはなりませんが、スペルミスを確認できるよう、コンソールに [maiagent] Unknown config options: ... 警告が表示されます。

基本

フィールド
型
必須
説明

webChatId

string

✅

Web Chat の一意な識別子です

baseUrl

string

✅

Web Chat のサービス URL です。SaaS では https://chat.maiagent.ai/web-chats です

contactId

string

連絡先 ID です（バックエンド連携で使用します。ユーザーの識別を参照してください）

auth

object

フロントエンドのID設定です。sourceId（必須）、name、contextData、mcpCredentials、ts と sig（署名検証が有効な場合は必須。署名検証を参照してください）を指定します。SDK の準備完了後に auth.setup() が自動実行されます

queryMetadata

object または string

ナレッジベースの検索範囲フィルターです（LLM prompt には入りません）

locale

string

インターフェースの言語です（例：zh-TW、en）。サポートする言語は MaiGPT モードのページの第5節を参照してください。優先順位は config > ユーザーの前回の選択 > ブラウザーの言語 > zh-TW です

ウィンドウモードと動作

フィールド
型
デフォルト値
説明

enabledWindowModes

string[]

['floating', 'sidebar']

利用可能なウィンドウモードです。最初の要素がデフォルトです。ウィンドウモードを参照してください

allowWindowModeSwitch

boolean

true

ウィンドウモードの切り替えボタンを表示するかどうかです（2つ以上のモードが有効な場合のみ意味があります）

showButton

boolean

true

チャットボタンを表示するかどうかです。false に設定した場合は、プログラムから MaiAgent.control.open() を呼び出して開きます

showChatNotification

boolean

false

ウィンドウが閉じているときに返信を受信した場合、ボタンの横に通知を表示するかどうかです

chatNotificationTitle

string

通知のタイトル文字列です

preventIosInputZoom

boolean

iOS Safari で入力欄にフォーカスしたときのページの自動拡大を防ぎます

container

string、HTMLElement または object

inline モード専用の埋め込みコンテナです。inline モードのコンテナを参照してください

targetElement

string または HTMLElement

MaiGPT モード専用の埋め込みコンテナです。MaiGPT モードを参照してください

maigptTitle

string

MaiGPT モード専用のサイドバーのブランドタイトルです。デフォルトでは MaiGPT を表示します

外観

サイズを指定するフィールドには、数値（px として扱われます）、または 'Npx'、'Nrem' 形式の文字列を指定できます。

フィールド
型
デフォルト値
説明

primaryColor

string

#1890ff

テーマカラーです（ボタンとインターフェースのメインカラー）

buttonSize

string または number

3rem

チャットボタンのサイズです

buttonRadius

string

50%

チャットボタンの角丸の半径です

buttonIcon

string

ボタンアイコンの画像 URL です（openIconHtml より優先されます）

openIconHtml

string

組み込み SVG

ボタンの「開く」状態のカスタム HTML です

closeIconHtml

string

組み込み SVG

ボタンの「閉じる」状態のカスタム HTML です

windowWidth

string または number

24rem

フローティングウィンドウの幅です

windowHeight

string または number

40rem

フローティングウィンドウの高さです

windowRadius

string

0.75rem

フローティングウィンドウの角丸の半径です

boxShadow

string

0.125rem 0.125rem 0.5rem #00000044

ボタンとウィンドウの影です

位置

フィールド
型
デフォルト値
説明

buttonPositionBottom

string または number

16（px）

ブラウザーウィンドウの下端からボタンまでの距離です

buttonPositionRight

string または number

16（px）

ブラウザーウィンドウの右端からボタンまでの距離です

windowPositionBottom

string

5rem

下端からフローティングウィンドウまでの距離です

windowPositionRight

string

1rem

右端からフローティングウィンドウまでの距離です

windowPosition

string

'center' に設定すると、フローティングウィンドウを中央に表示します

チャットボタンはドラッグで移動でき、位置はブラウザーに記憶されます。再読み込み時に記憶した位置が現在のウィンドウの範囲外にある場合は、安全な位置に自動で戻ります。

ボタン位置の決定順序

  • buttonPositionBottom／buttonPositionRight が、ボタン位置を設定する唯一のフィールドです。ユーザーがドラッグした位置は、そのブラウザーのウィンドウ状態にのみ保存され、再度ドラッグするかサイトデータを削除するまで設定値より優先されます。

  • チャットウィンドウを開くとき（ボタンのクリックまたは MaiAgent.control.open() の呼び出し）、フローティングウィンドウはボタンの現在位置を基準に配置され、ボタン自体は移動しません。ウィンドウを閉じた後も、ボタンは同じ場所に残ります。

  • ブラウザーウィンドウのサイズが変わると、ユーザーがドラッグした位置は比率に応じて調整され、表示範囲内に収まります。設定値で配置されたボタンは CSS によって自動的に追従します。

  • ボタン位置を固定してユーザーによる移動を禁止するための、ドラッグを無効にする設定は現在ありません。showButton: false で組み込みボタンを非表示にし、MaiAgent.control.open() を呼び出す独自のボタンを配置できます（完全なサンプルを参照してください）。

  • 位置がずれて見える場合は、まずページの CSS がボタンコンテナの position、bottom、right を上書きしていないか確認し、そのサイトのブラウザーデータを削除して記憶した位置をリセットしてください。

5. SDK API

SDK の初期化後は、グローバルな MaiAgent オブジェクトで操作できます。すべてのメソッドは、SDK の準備完了後に呼び出してください（トラブルシューティングの利用可否の確認を参照してください）。

ウィンドウ制御 MaiAgent.control

メソッド
説明

open()

チャットウィンドウを開きます

close()

チャットウィンドウを閉じます

isOpen()

チャットウィンドウが開いているかどうかを返します（boolean）

同等のグローバルショートカット window.maiagentOpenChat() / window.maiagentCloseChat() もあります。

メッセージ MaiAgent.chat

メソッド
説明

send(content)

ユーザーとしてテキストメッセージを送信します

clearHistory()

現在の会話のメッセージ履歴を削除します

newConversation()

新しい会話を開始します

イベント MaiAgent.events

メソッド
説明

on(eventType, callback)

イベントリスナーを登録します

off(eventType, callback)

イベントリスナーを削除します（同じ callback 参照を渡す必要があります）

監視できるイベントは次のとおりです。

イベント
発火のタイミング
callback 引数

messageReply

AI Agent の返信を受信したときです

解析済みのオブジェクトです：{ content: string, sender?: { name, avatar }, timestamp?: number, ... }

sdkReady

SDK の初期化が完了したときです

—

authReady

auth.setup() が完了したときです

—

iframeReady

チャットウィンドウの iframe の準備が完了したときです

—

言語と音声

メソッド
説明

MaiAgent.locale.set(lang)

インターフェースの言語を切り替えます（例：'zh-TW'、'zh-CN'、'en'）。サポートする言語は MaiGPT モードのページの第5節を参照してください

MaiAgent.speech.set(lang, provider?)

音声認識と音声合成の言語を設定します。provider で音声サービスのプロバイダーを指定できます（例：'azure'）

locale が影響するのはインターフェースの文字列のみで、AI の回答言語には影響しません。AI の回答言語の設定は多言語サポートを参照してください。

ID MaiAgent.auth

メソッド
説明

setup(authConfig)

連絡先を作成または対応付けし、ユーザー情報を適用します。Promise<string | null>（成功時は contactId）を返します。authConfig のフィールドは config の auth と同じです

signOut()

現在のユーザーをログアウトさせ、匿名状態に戻し、contextData をクリアします。フロントエンドにのみ作用します。バックエンドですでに紐付けられたツールの認証情報は別途失効させる必要があります。ログアウトと認証情報の失効を参照してください

config に auth がある場合、SDK が自動的に setup() を呼び出すため、手動で実行する必要はありません。SPA でユーザーがログイン／ログアウトする場合や、contextData を更新する場合にのみ手動で呼び出します。

6. 完全なサンプル

7. トラブルシューティング

症状
確認事項

ボタンが表示されません

maiagentChatbotConfig が SDK スクリプトより前に定義されているか、webChatId / baseUrl が正しいか、コンソールにエラーがないかを確認します

コンソールに Unknown config options: ... が表示されます

設定オプションリファレンスと照合し、フィールド名のスペルを確認します

MaiAgent is not defined

SDK の読み込みが完了していません。DOMContentLoaded の後に呼び出すか、先に typeof MaiAgent !== 'undefined' を確認します

イベントリスナーが発火しません

イベント名が正しいかを確認します（MaiAgent.EVENT_TYPES 定数の使用を推奨します）。off() には on() と同じ関数参照を渡す必要があります

端末を変えると会話が表示されなくなります

匿名状態の会話はブラウザ単位です。端末間で共有するには auth または contactId を設定します（ユーザーの識別を参照してください）

auth を設定してもユーザー情報が反映されません（400 エラー）

Web Chat に「埋め込みを許可するドメイン」が設定されている場合、リスト内のドメインのページのみユーザー情報を同期できます。埋め込みページのドメインがリストに追加されているか確認します

ボタンの位置が正しくありません

ページの CSS とボタンのスタイルが競合していないか、位置パラメータの形式が正しいか（数値、px、rem）を確認します。ドラッグ後の位置はブラウザに記憶されます。ボタン位置の決定順序を参照してください

自分で iframe を配置し、postMessage でチャットウィンドウと通信したいです

サポートされていません。SDK とチャットウィンドウの iframe 間の postMessage メッセージは SDK の内部プロトコルであり、形式はバージョンにより変わります。他の送信元からのメッセージも受け付けません。埋め込みコードで SDK を読み込み、イベント（messageReceived など）でメッセージを受信し、MaiAgent.chat で送信してください。ページ内に固定したチャット領域が必要な場合は inline モードを使用してください

SDK を安全に呼び出します：

前へソフトウェアベンダー向け連携ガイド：顧客向けに AI Agent を組み込みます
次へMaiGPT モードの埋め込み

最終更新

役に立ちましたか？