For the complete documentation index, see llms.txt. This page is also available as Markdown.

Web Chat SDK 操作コマンド

本記事では、MaiAgent の Web Chat SDK の使い方をご紹介します

MaiAgent SDK は、開発者が MaiAgent チャットボットを任意の Web サイトに簡単に統合できるよう、包括的な JavaScript API を提供しています。

一、初期化について

埋め込みスクリプトの取得方法については、🌐対話プラットフォームの連携:Web サイト をご参照ください。

この手順に従って操作すると、スクリプトに webChatId パラメータが自動的に付与されます。

埋め込みスクリプトの読み込み後、システムは自動的に document.body.onload イベントハンドラーを登録して Web Chat の初期化を実行するため、手動で登録を呼び出す必要はありません。初期化のタイミングを制御したい場合(たとえば他のリソースの読み込み完了を待つ、またはレンダリングを遅延させる場合)は、以下の方法を利用できます。

  1. スクリプトの遅延読み込みembed.min.js の読み込みタイミングを制御します

  2. 手動での初期化トリガー:適切なタイミングで document.body.onload() メソッドを呼び出します

この仕組みにより、開発者は DOM レンダリングと Web Chat の初期化を分離でき、より柔軟な統合方法を実現できます。

注意事項

  • システムは連絡先 API を通じて Contact ID が付与されたことを確認した後に初期化を行います。

  • Query Metadata を利用することで、Web Chat の初期化時点でナレッジマネジメント権限を付与できます

ナレッジマネジメント権限の詳細については、🌐ナレッジマネジメント権限(Query Metadata / メタデータ照会)概要↗をご参照ください。

二、クイックスタート

1. SDK の読み込み

2. API の使用

三、基本設定

SDK を読み込む前に、まず maiagentChatbotConfig オブジェクトを設定する必要があります。

詳細なパラメータの説明については、下記の 設定オプション をご参照ください。

四、API 機能

1. チャット制御

MaiAgent.control.open()

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

MaiAgent.control.close()

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

MaiAgent.control.isOpen()

チャットウィンドウが開いているかを確認します

2. メッセージ管理

MaiAgent.chat.send(content)

チャットボットにメッセージを送信します

MaiAgent.chat.clearHistory()

チャット履歴を消去します

MaiAgent.chat.newConversation()

新しい会話を開始します

3. イベント監視

MaiAgent.events.on(eventType, callback)

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

MaiAgent.events.off(eventType, callback)

イベントリスナーを削除します

4. 言語設定

Web Chat の言語と音声制御

MaiAgent の対応言語については、多言語対応 をご参照ください。

  • Web Chat は繁体字中国語、簡体字中国語、英語、日本語、韓国語、タイ語など多言語に対応しており、今後も継続的に拡充していきます

  • 埋め込み後は globalThis.MaiAgent オブジェクトへグローバルにアクセスでき、テキストまたは音声の言語を設定できます

  • 「繁体字中国語」および「簡体字中国語」以外の言語については、「言語コード」を指定するだけで設定できます

言語設定の例

Web サイトのニーズに応じて、異なる言語インターフェースや音声オプションを設定できます。

  • テキストインターフェース:繁体字中国語(zh-TW)、簡体字中国語(zh-CN)、英語(en)などに設定できます

  • 音声設定:ASR(音声認識)および TTS(音声合成)で使用する言語を設定できます

MaiAgent.speech.set(lang, provider)

音声の言語とプロバイダーを設定します

MaiAgent.locale.set(lang)

インターフェースの言語を設定します

五、設定オプション

1. 基本設定

オプション
必須
デフォルト値
説明

webChatId

string

はい

-

チャットボットの一意の識別子

baseUrl

string

はい

-

API サービスのベース URL

contactId

string

いいえ

-

連絡先識別子

queryMetadata

object/string

いいえ

-

追加の照会メタデータ

2. 外観設定

オプション
デフォルト値
説明

primaryColor

string

#1890ff

テーマカラー

buttonSize

string

48

ボタンのサイズ(ピクセル)

buttonRadius

string

50%

ボタンの角丸

windowWidth

string

24rem

チャットウィンドウの幅

windowHeight

string

40rem

チャットウィンドウの高さ

windowRadius

string

0.75rem

チャットウィンドウの角丸

boxShadow

string

0.125rem 0.125rem 0.5rem #00000044

影の効果

3. 位置設定

オプション
デフォルト値
説明

buttonPositionBottom

string

16

ボタンの下端からの距離(ピクセル)

buttonPositionRight

string

16

ボタンの右端からの距離(ピクセル)

windowPositionBottom

string

5rem

チャットウィンドウの下端からの距離

windowPositionRight

string

1rem

チャットウィンドウの右端からの距離

4. 動作設定

オプション
デフォルト値
説明

allowDrag

boolean

true

チャットボタンのドラッグを許可するか

5. カスタムアイコン

オプション
デフォルト値
説明

closeIconHtml

string

デフォルト SVG

カスタム閉じるアイコンの HTML

openIconHtml

string

デフォルト SVG

カスタム開くアイコンの HTML

六、イベントタイプ

1. 監視可能なイベント

イベント名
説明
データ形式

messageReply

チャットボットの返信を受信したときに発火

{ content: string, timestamp: number, ... }

2. 内部イベント(参考)

イベント名
説明

setSpeechLanguage

音声言語を設定

setLocale

インターフェース言語を設定

sendMessage

メッセージを送信

clearHistory

履歴を消去

newConversation

新しい会話を開始

closeBubbleWindow

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

sdkReady

SDK 準備完了

七、完全なサンプル

以下は、完全な統合サンプルです。

八、応用的な使用テクニック

1. 動的な設定更新

2. エラー処理

3. 他のシステムとの統合

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

1. よくある問題

  1. SDK が読み込まれない

    • maiagentChatbotConfig が SDK スクリプトより前に定義されているか確認してください

    • ネットワーク接続とスクリプト URL が正しいか確認してください

  2. チャットウィンドウが開かない

    • webChatIdbaseUrl の設定が正しいか確認してください

    • ブラウザのコンソールにエラーメッセージがないか確認してください

  3. イベントリスナーが機能しない

    • DOM の読み込み完了後にイベントリスナーを登録しているか確認してください

    • イベント名が正しいか確認してください

  4. ボタンの位置が異常

    • CSS の競合を確認してください

    • 位置パラメータの形式が正しいか確認してください

Last updated

Was this helpful?