チャットシナリオへのURLクエリパラメータの渡し方
このチュートリアルでは、ウェブサイトのURLに含まれるクエリパラメータをチャットシナリオで使用する方法を説明します。なお、本チュートリアルでは、以下の準備がすでに整っていることを前提としています：
手順
顧客がウェブサイトを閲覧する際、URLにはクエリパラメータという形で貴重な情報が含まれていることがよくあります。これらのパラメータを取得し、活用することで、チャット体験を向上させることができます。例えば、顧客が次のようなURLを持つウェブサイト上のページからWebチャットウィジェットを開いた場合を考えます：
https://example.com/checkout.html?cart_id=6789-defg-h4i5&user_id=abc-123
このケースでは、クエリパラメータは?の後に続くすべての部分となります：
cart_id=6789-defg-h4i5&user_id=abc-123
これを解析し、Webチャットウィジェット経由でシナリオに渡すと、以下のシナリオ変数が次のように設定されます：
$(item.externalChatData.cart_id)には、値6789-defg-h4i5が設定されます$(item.externalChatData.user_id)には、値abc-123が設定されます
一般的に、クエリ文字列に含まれるその他の key=value ペアの値は、シナリオ変数 $(item.externalChatData.key) を参照することで、シナリオ内で利用可能になります。以下のステップでは、その方法を説明します：
- JavaScript を使用して個々のクエリパラメータを抽出します。
- チャットウィジェットの設定を編集し、抽出したクエリパラメータをチャットシナリオに送信します。
- シナリオ変数を使用して、各クエリパラメータの値にアクセスします。
- チャットを開き、クエリパラメータがエージェントにどのように表示されるかを確認します。
1. クエリパラメータの抽出
以下のステップでは、URL からクエリパラメータを解析する 1 つの方法をご紹介します。
- クエリパラメータを変数
queryParamsに抽出するために、以下の JavaScript スニペットをウェブサイトに追加してください：
<script>
// URLのクエリパラメータを抽出してオブジェクトにパースする関数
function getQueryParams() {
// 現在のURLのクエリ文字列（「?」以降のすべて）からURLSearchParamsオブジェクトを作成します
const params = new URLSearchParams(window.location.search);
// キーと値のペアを格納するための空のオブジェクトを初期化します
const queryParams = {};
// URLSearchParams オブジェクト内の各キー・値のペアを順に処理します
for (const [key, value] of params) {
// 各キー・値のペアを queryParams オブジェクトに追加します
queryParams[key] = value;
}
// すべてのクエリパラメータを含むオブジェクトを返します
return queryParams;
}
// 関数を実行し、結果を queryParams 定数に格納します
const queryParams = getQueryParams();
// デバッグのために、抽出されたクエリパラメータをコンソールに出力します
console.log("Query Parameters:",queryParams);
</script>
- ウェブサイトのURLの末尾に
?cart_id=6789-defg-h4i5&user_id=abc-123を追加し、ページを読み込んでください
queryParamsのコンテンツがコンソールに記録され、オブジェクト{cart_id: "6789-defg-h4i5", user_id: "abc-123"}として表示されることを確認してください
queryParams JavaScript 変数のコンテンツ2. チャットウィジェットの設定
チャットウィジェットを使用すると、設定中にJavaScript 変数をシナリオに渡すことができます。
- 上記の JavaScript 関数をチャットウィジェットに組み込み、クエリパラメータをシナリオに渡してください。スクリプトの重要なポイントにご注意ください：
- まず、関数
getQueryParams()が定義されます - 次に、
const queryParams = getQueryParams();という行で、queryParamsの値が設定されます - 最後に、キーと値のペア
parameters:queryParamsをSERVICE_PATTERN_CHAT_CONFIGに追加します
- まず、関数
<link type="text/css" rel="stylesheet" href="https://example.brightpattern.com/clientweb/chat-client-v4/css/form.css">
<script type="text/javascript">
function getQueryParams() {
const params = new URLSearchParams(window.location.search);
const queryParams = {};
for (const [key, value] of params) {
queryParams[key] = value;
}
return queryParams;
}
const queryParams = getQueryParams();
SERVICE_PATTERN_CHAT_CONFIG = {
appId: '70a6624585ef2b0981fed84fcd12d4db',
apiUrl: 'https://example.brightpattern.com/clientweb/api/v1',
tenantUrl: 'example.brightpattern.com',
chatPath: 'https://example.brightpattern.com/clientweb/chat-client-v4/',
// Set the new variable "queryParams" as the value for the custom 'parameters' sent when configuring the chat widget
parameters:queryParams
};
</script>
<script src="https://example.brightpattern.com/clientweb/chat-client-v4/js/init.js"></script>
appId、apiUrl、tenantUrl、およびchatPathが、お使いのチャットウィジェットに合わせて正しい値で設定されていることを確認してください。
- ウェブページを開き、チャットウィジェットが正しく読み込まれることを確認してください。
3. シナリオ変数を使用してクエリパラメータの値にアクセスする
チャット設定の parameters キーに渡されたデータには、シナリオ変数 $(item.externalChatData) を通じてアクセスできます。前述の通り、クエリ文字列に含まれる key=value ペアの値は、シナリオ変数 $(item.externalChatData.key) を参照することで、シナリオ内で利用可能です。
例として、次の URL を使用します：
https://example.com/checkout.html?cart_id=6789-defg-h4i5&user_id=abc-123
この場合、2つのクエリパラメータが存在し、以下のシナリオ変数を通じてアクセスできます：
$(item.externalChatData.cart_id)には、値6789-defg-h4i5が設定されます$(item.externalChatData.user_id)には、値abc-123が設定されます
クエリ文字列から取得した cart_id および user_id の値を、内部メッセージ経由でエージェントに表示するようにシナリオを設定するには：
- このチャットウィジェットに関連付けられているチャットシナリオを開きます。以下の3つのブロックを順に追加してください：
- エージェント検索（チャット） ブロックを、既定値のまま追加します。
- 内部メッセージ ブロックを、クエリパラメータの値を表示するように設定します（次のステップで説明）。
- チャット接続 ブロックを、既定値のまま追加します。
- 「内部メッセージ」ブロックを選択し、指示通りに各フィールドを設定してください：
- タイトルテキスト：ブロックの目的を理解しやすくするためのオプション名です。単に「注文情報」と設定してください。
- ユーザー名：メッセージを表示すべき対象者を指定します。シナリオ変数
$(user.loginId)は、「エージェント検索（チャット）」ブロックで選択されたエージェントのログインIDを提供するため、顧客のチャットに応答したエージェント自身が、注文情報を含む内部メッセージを確認できるようになります。 - メッセージ：エージェントに表示するテキストです。クエリ文字列のデータを表示するには、以下に示すように
$(item.externalChatData)シナリオ変数を使用してください：Cart ID $(item.externalChatData.cart_id) User ID $(item.externalChatData.user_id)
- タイトルテキスト：ブロックの目的を理解しやすくするためのオプション名です。単に「注文情報」と設定してください。
- 「エージェント検索」および「チャット接続」ブロックは、既定の設定のままにしておいてください。シナリオを保存してください。
4. シナリオのテスト
ここで、設定全体をテストし、ウェブサイトからチャットウィジェットを経由してチャットシナリオへ渡され、最終的にエージェントに表示されるクエリパラメータを確認します。
- シナリオからのチャットを処理できるエージェントとして、エージェントデスクトップアプリケーションにログインしてください。
- チャットウィジェットが設定されているウェブサイトにアクセスしてください。URLにクエリパラメータを追加し（例：
https://example.com/checkout.html?cart_id=6789-defg-h4i5&user_id=abc-123）、ページを再読み込みし、チャットウィジェットを開いて新規チャットセッションを開始してください。
- エージェントデスクトップからチャットを受け入れ、クエリパラメータの値が内部メッセージに表示されていることを確認してください：
その他のアイデア
内部メッセージを使用してエージェントにデータを表示するのは、数ある可能性の中でも単純な一例に過ぎません。シナリオ変数を使用して、CRMやWebスクリーンポップ用のURLを作成したり、Ask a Botから自動応答を取得したり、AIエージェント用のカスタム指示を作成したりすることを検討してください。