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 アシスタントをお客様のウェブサイトに設置できます。埋め込みコードが embed.min.js（以下 SDK）を読み込むと、SDK はページ上にチャットボタンと iframe のチャットウィンドウを作成し、プログラムから操作できるグローバル MaiAgent JavaScript API を提供します。

本ページは Web Chat 埋め込みの完全な技術リファレンスです。関連トピック：

一、クイックスタート

ページの </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 のコンテナ mount 待ちや遅延レンダリングなど）：

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

  2. 手動トリガー：先に window.maiagentChatbotConfig を設定してから、document.body.onload() を呼び出します

同一ページで SDK は一度だけ初期化され、重複読み込みは無視されます。

二、ウィンドウモード

enabledWindowModes 配列でユーザーが利用できるウィンドウモードを決定します。先頭の要素がデフォルトモードです。未設定の場合は ['floating', 'sidebar'] と同等です。

モード
形態
適した用途

floating

ページ右下に重なるフローティングウィンドウ。ボタンのドラッグ移動やウィンドウのサイズ調整が可能（320×400 〜 900×900 px）

一般的なカスタマーサポート、相談

sidebar

ウィンドウ右側に密着するサイドバー（幅 320〜800 px、ドラッグで調整可能）。ページコンテンツは自動で縮小して退避します

ページを見ながら会話する業務シーン

maigpt

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

ページのメイン機能領域、サイト全体の AI 入口。MaiGPT モードを参照

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

  • maigpt を先頭要素にすると MaiGPT モードになり、他の要素は無効です（このモードは切り替えを提供しません）

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

3 つのモードの実際の画面

三、ユーザーの識別

Web Chat は連絡先（Contact）に紐付いているかどうかで、3 つの身元レベルに分かれます：

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

匿名

何も設定しない

ブラウザ単位で保持

✖

フロントエンド auth

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

連絡先に紐付き、デバイスをまたいで利用可能

✔

バックエンド連携

バックエンドが身元同期 API を呼び出して contactId を取得し、config に contactId を指定

連絡先に紐付き、デバイスをまたいで利用可能

✔

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

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

バックエンド連携：お客様のバックエンドがユーザーのログイン時に同じ API を呼び出し（MCP ツール資格情報の紐付けも同時に可能）、返された contactId を会員データに保存し、フロントエンドは contactId のみを指定します。

どちらを選ぶか：

  • 「ユーザーを認識し、デバイスをまたいで会話を保持する」だけでよい → フロントエンド auth が最も手軽です

  • ユーザーの Access Token を MCP ツール資格情報に紐付けたい（AI にユーザー権限でお客様の API を呼び出させたい）が、token をフロントエンドページのソースコードに出したくない → バックエンド連携

  • 両者の基盤は同じ連絡先の仕組みであり、sourceId が同一であれば同一連絡先とみなされ、併用も可能です

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

セキュリティ上の注意

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

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

  • 署名検証が無効な場合：身元同期は公開エンドポイントであるため、推測可能な sourceId はなりすまし可能な身元と同義です。UUID などの推測不可能な値を使用し、連番、メールアドレス、電話番号は使用しないでください。

  • 署名検証が有効な場合：セキュリティは sourceId 自体ではなく署名によって確保されるため、学籍番号、従業員番号、登録メールアドレスなどの可読値をそのまま使用できます。シークレットはお客様のサーバーにのみ存在するため、sourceId が知られても、シークレットがなければ有効な署名を計算できません。

署名検証

Web Chat のログイン設定で「埋め込み側で Source ID を使用したログイン不要の会話を許可」を有効にすると、お客様のウェブサイトにログイン済みのユーザーは、チャットウィンドウでもう一度ログインする必要がなくなります。スイッチとシークレットは管理画面のログイン設定タブにあります。操作方法については、ユーザーマニュアルの連絡先 Source ID を使用したログイン不要の会話を参照してください。

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

検証方法
動作

署名検証を必須にする

ts と sig を指定し、署名検証に成功した場合のみ許可します

Source ID のみ

署名を検証せず、sourceId が指定されていれば許可します。テストまたは閉鎖された社内ネットワーク環境にのみ適しています

署名アルゴリズム

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

検証ルール

ルール
説明

有効期限

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

時刻の許容差

60 秒のずれを許容します。現在より 60 秒を超えて未来のタイムスタンプは常に拒否します

1 回限り

同じ署名は 1 回だけ正常に使用できます。署名自体がリプレイ攻撃を防止する nonce になります

Web Chat への紐付け

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

拒否レスポンス

すべての失敗理由に対して同じレスポンスを返し、理由も sourceId の存在有無も外部に開示しません

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

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

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

署名検証エラーのトラブルシューティング

管理画面のログイン設定にある「署名検証エラーログを表示」には、最近のエラーイベントと理由が表示され、トラブルシューティングに利用できます：

理由
主な原因

署名の期限切れ

サーバーの時刻がずれているか、フロントエンドが署名をキャッシュしています

タイムスタンプが許容される未来の範囲を超過

サーバーの時刻が 60 秒を超えて進んでいます

署名の不一致

シークレットが一致していないか、署名文字列の組み立て方が誤っています（区切り文字は半角ピリオドです）

タイムスタンプまたは署名が不足

ts または sig が指定されていません

署名が使用済み

同じ署名が 2 回送信されました

Source ID が複数の連絡先に対応

この Web Chat に同じ sourceId の連絡先レコードが重複して存在します

埋め込み許可ドメイン

Web Chat の「埋め込み許可ドメイン」リストは、どのウェブサイトが身元同期を完了できるかを制限します（auth とバックエンドの setup-contact-credentials の両方がこの制約を受けます）。このリストは現在 MaiAgent チームがお客様に代わって設定します。許可したいドメインのリストを連携窓口の担当者にお知らせください。

リストの状態
動作

空リスト（デフォルト）

オリジンを制限しない

https://example.com を記載

scheme＋host（＋port）の完全一致

*.example.com を記載

example.com とそのすべてのサブドメインを含む（scheme／port は問わない）

リストに値はあるがすべて形式が無効

すべてのオリジンを拒否（fail closed）。サイレントに無制限へフォールバックすることはありません

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

四、設定オプションリファレンス

window.maiagentChatbotConfig がサポートするすべてのフィールドです。未知のフィールドを設定してもエラーにはなりませんが、console に [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

フロントエンド身元設定：sourceId（必須）、name、contextData、mcpCredentials、ts と sig（署名検証を有効にした場合は必須。署名検証を参照）。SDK は準備完了後に自動で auth.setup() を実行します

queryMetadata

object または string

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

locale

string

インターフェース言語（zh-TW、en など）。サポート一覧は MaiGPT モードページ第五節を参照。優先順位：config > ユーザーの前回の選択 > ブラウザ言語 > zh-TW

現行バージョンでは auth を渡すと console に Unknown config options: auth と誤って報告されますが、機能には影響しないため、この警告は無視して構いません。

ウィンドウモードと動作

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

enabledWindowModes

string[]

['floating', 'sidebar']

利用可能なウィンドウモード。先頭がデフォルト。ウィンドウモードを参照

allowWindowModeSwitch

boolean

true

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

showButton

boolean

true

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

showChatNotification

boolean

false

ウィンドウを閉じている間に返信を受け取った際、ボタンの横に通知を表示するか

chatNotificationTitle

string

通知のタイトルテキスト

preventIosInputZoom

boolean

iOS Safari で入力欄フォーカス時のページ自動拡大を防止

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' を設定するとフローティングウィンドウが中央に表示されます

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

五、SDK API

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

ウィンドウ制御 MaiAgent.control

メソッド
説明

open()

チャットウィンドウを開く

close()

チャットウィンドウを閉じる

isOpen()

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

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

メッセージ MaiAgent.chat

メソッド
説明

send(content)

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

clearHistory()

現在の会話の履歴メッセージをクリア

newConversation()

新しい会話を開始

イベント MaiAgent.events

メソッド
説明

on(eventType, callback)

イベントリスナーを登録

off(eventType, callback)

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

監視できるイベント：

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

messageReply

AI アシスタントの返信を受信したとき

パース済みオブジェクト：{ content: string, sender?: { name, avatar }, timestamp?: number, ... }

sdkReady

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

—

authReady

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

—

iframeReady

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

—

言語と音声

メソッド
説明

MaiAgent.locale.set(lang)

インターフェース言語を切り替え。'zh-TW'、'zh-CN'、'en' など。サポート一覧は MaiGPT モードページ第五節を参照

MaiAgent.speech.set(lang, provider?)

音声認識と音声合成の言語を設定。provider で音声サービスプロバイダーを指定可能（'azure' など）

locale はインターフェースのテキストにのみ影響し、AI の回答言語には影響しません。AI の返信言語の設定は多言語サポートを参照してください。

身元 MaiAgent.auth

メソッド
説明

setup(authConfig)

連絡先を作成または照合して身元を適用し、Promise<string | null> を返します（成功時は contactId）。authConfig のフィールドは config の auth と同じです

signOut()

現在の身元からログアウトし、匿名状態に戻して contextData をクリアします。フロントエンドにのみ作用します。バックエンドで紐付け済みのツール資格情報は別途失効が必要です。ログアウトと資格情報の失効を参照

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

六、完全な例

七、トラブルシューティング

症状
確認事項

ボタンが表示されない

maiagentChatbotConfig が SDK スクリプトより前に定義されているか。webChatId / baseUrl は正しいか。console にエラーがないか

console に Unknown config options: ... が表示される

設定オプションリファレンスと照合してフィールドのスペルを確認してください（auth の誤検知は無視して構いません）

MaiAgent is not defined

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

イベントリスナーが発火しない

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

デバイスを変えると会話が消える

匿名状態の会話はブラウザ単位で保持されます。デバイスをまたぐには auth または contactId を設定してください（ユーザーの識別を参照）

auth を設定しても身元が有効にならない（400 エラー）

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

ボタンの位置がおかしい

ページの CSS がボタンのスタイルと競合していないか、位置パラメータの形式が正しいか（数値、px、rem）を確認してください

SDK を安全に呼び出す：

前へナレッジベースの利用—作成と操作
次へMaiGPT モード埋め込み

最終更新

役に立ちましたか？