この記事はバージョン Spring ’26 において執筆しています。
現在の動作と異なる場合がありますので、ご認識おきください。
Experience CloudのLWRサイトでMessaging for In-App and Web(MIAW)を利用する際、ログインユーザーの情報をチャットに連携したいケースは頻繁に発生します。しかしMIAWの仕様上、ユーザーのID情報をメッセージングレコードとそれに関連するレコードに渡すには多少の開発が必要です。
この記事では、LWRサイトから非表示の事前チャット項目を通じてオムニチャネルフローに変数を渡すための、JavaScriptの「Pre-Chat API」とSalesforce側のマッピング設定を組み合わせた実装手順を解説します。
今回ご紹介する方法は開発を極力減らしたやり方ですのでご安心ください。
Step 1: メッセージング設定で「カスタムパラメータ」を作成する
事前チャットAPIを介してカスタムデータを渡すには、まずSalesforceの「メッセージング設定」でパラメータの受け皿を定義する必要があります。ここで設定するAPI参照名は、後のJavaScriptコードと完全に一致させる必要があります。
- 対象のチャネルを開き、新しい「カスタムパラメータ」を作成します。
- パラメータ名（API参照名）の例：
userIdParam
Step 2: メッセージング設定で「パラメータの対応付け」を行う
続けて、メッセージング設定のパラメーターの対応付けでカスタムパラメーターとフロー変数を紐づけます。
この設定を忘れると、フローに値が自動代入されません。
Step 3: 組み込みサービスリリースにパラメータを紐付ける
作成したパラメータを、対象のチャネルの「組み込みサービスリリース」で非表示項目としてマッピングします。この設定により、チャットウィジェットが指定されたパラメータを受け取れるようになります。
- 組み込みサービスリリースの設定画面を開き、「事前チャット」の設定セクションに移動します。
- Step 1で作成した
userIdParam - 最後に「公開」をお忘れなく。
Step 4: LWR側でLWCを用いて値を渡す
LWRサイトではUIを持たない（ヘッドレスな）カスタムLWCを作成し、エクスペリエンスビルダー上でフッターなど共通部分に配置してバックグラウンド処理させるアプローチが必要です。
サンプル実装
チャットウィジェットの準備完了イベント（onEmbeddedMessagingReady）に合わせて、ログインユーザーのIDをセットするLWCを作成します。
hiddenPreChatLwc.js
import { LightningElement } from 'lwc';
import USER_ID from '@salesforce/user/Id';
export default class HiddenPreChatLwc extends LightningElement {
// イベントの多重発火を防ぐためのフラグ
hasDispatched = false;
/**
* コンポーネントがDOMにレンダリングされた後に実行されます。
* SSR環境でのエラーを回避するため、クライアント側（ブラウザ）で
* 確実に実行されるこのライフサイクルフックを使用します。
*/
renderedCallback() {
if (this.hasDispatched) {
return;
}
// ブラウザ環境であり、かつユーザーIDが取得できている場合のみ処理を実行します
if (typeof window !== 'undefined' && USER_ID) {
this.hasDispatched = true;
// カスタムイベントを作成し、detailオブジェクトに取得したユーザーIDを格納します
const userIdEvent = new CustomEvent('passuserid', {
detail: { userId: USER_ID }
});
// 動作確認用のコンソールログ
console.log('【LWC】ユーザーIDの取得とイベントの発火を実行します: ', USER_ID);
// windowオブジェクトに対してイベントを発火し、ヘッドマークアップ側へ伝達します
window.dispatchEvent(userIdEvent);
}
}
}hiddenPreChatLwc.js-meta.xml
エクスペリエンスビルダーでコンポーネントを配置できるように、ターゲットを設定します。
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
<apiVersion>66.0</apiVersion>
<isExposed>true</isExposed>
<targets>
<target>lightningCommunity__Page</target>
<target>lightningCommunity__Default</target>
</targets>
</LightningComponentBundle>LWRサイトに配置
どの画面にいても処理できるように、組み込みメッセージングコンポーネントと同じくフッターに配置しましょう。
Step 5: ヘッドマークアップの実装
エクスペリエンスビルダーの「設定」>「詳細」>「ヘッドマークアップを編集」を開き、LWCからの値を受信してAPIに渡すスクリプトを記述します。最後にサイトを公開するのをお忘れなく。
<!-- LWCから受け取ったユーザーIDを非表示事前チャット項目に保持する処理 -->
<script type="text/javascript">
// LWCから受け取ったユーザーIDを保持するための変数
let currentUserId = null;
// メッセージングAPIの準備が完了したかを判定するためのフラグ
let isMessagingReady = false;
/**
* 事前チャット項目を設定する関数
* ユーザーIDの受信と、APIの準備の両方が完了している場合のみ実際の処理を行います
*/
function setPrechatFieldsIfReady() {
if (isMessagingReady && currentUserId) {
try {
// 対象のカスタムパラメータ名（Salesforce側のAPI参照名）と値を指定して設定します
// 注意: "userIdParam" は環境に合わせて大文字小文字を完全に一致させてください
embeddedservice_bootstrap.prechatAPI.setHiddenPrechatFields({
"userIdParam": currentUserId
});
console.log("【Head Markup】事前チャット項目の設定に成功しました。渡したID: ", currentUserId);
} catch (error) {
// エラーが発生した場合は、Proxyオブジェクトの中身を展開して詳細を表示します
console.error("【Head Markup】事前チャット項目の設定に失敗しました。詳細: ", JSON.parse(JSON.stringify(error)));
}
}
}
// 1. LWCから発火されるカスタムイベント 'passuserid' をリッスンします
window.addEventListener("passuserid", function(event) {
console.log("【Head Markup】LWCからユーザーIDを受信しました");
currentUserId = event.detail.userId;
setPrechatFieldsIfReady();
});
// 2. メッセージングウィジェットの準備完了イベントをリッスンします
window.addEventListener("onEmbeddedMessagingReady", function() {
console.log("【Head Markup】メッセージングAPIの準備が完了しました");
isMessagingReady = true;
setPrechatFieldsIfReady();
});
</script>なぜ「リレー方式」が必要なのか？
- LWR環境において、MIAWのAPI（
embeddedservice_bootstrap）を安全に呼び出せる場所は「ヘッドマークアップ（<head>）」内のみです。LWCから直接呼び出すとLWSによりブロックされます。 - 一方で、ログインユーザーのID（
@salesforce/user/Id）を動的に取得できるのは「LWC」のみです。
このアーキテクチャの溝を埋めるため、以下の流れで処理を構築しています。
- LWCでユーザーIDを取得し、カスタムイベントとしてブラウザ全体に発火（送信）する。
- ヘッドマークアップ側でそのイベントを受信し、安全な領域からPre-Chat APIを呼び出す。
Step 6: オムニチャネルフローで変数として受け取る
インバウンドオムニチャネルフロー内で、設定したカスタムパラメータと同じAPI参照名の「入力可能」な変数を準備することで、値を受け取ることができます。
インバウンドオムニチャネルフローとは、顧客からの問い合わせ（チャット、メッセージ、音声通話、ケースなど）を最適なエージェントやキューまたはAgentforceに動的に転送（ルーティング）する初回のオムニチャネルフローのことです。
①はじめにAgentforceエージェントが対応して、②次に人間のオペレーターが対応する場合、①で振り分けを行うのがインバウンドオムニチャネルフローとなります。
フローの入力変数について
インバウンドオムニチャネルフローがMessagingチャットからトリガーされた際、以下の変数が自動的に入力可能となります。
recordId（テキスト型）：対象の「メッセージングセッション（MessagingSession）」レコードのIDが自動的に格納されます。userIdParam（テキスト型）：パラメータの対応付けを行っているので事前チャットAPI（LWC＋ヘッドマークアップ）から渡された値が格納されます。
フロー内の具体的な処理ステップ
上記2つの変数を活用し、フロー内で以下の順序で要素を配置して処理を構成します。
- レコードの取得（メッセージングセッションの特定）
- オブジェクト: メッセージングセッション (MessagingSession)
- 検索条件:
Idが{!recordId}と一致する - 目的: このセッションに紐づく「メッセージングユーザー（MessagingEndUser）」のIDを取得するため。
- レコードの取得（ログインユーザー情報の特定）
- オブジェクト: ユーザー (User)
- 検索条件:
Idが{!UserIdParam}と一致する - 目的: ログインしているExperience Cloudユーザーの「取引先責任者ID (ContactId)」を取得するため。
- 決定分岐（ユーザーの責任者IDが存在するかどうか）
- 条件: 手順2で取得したユーザーの手順2で取得したユーザーの
ContactIdが Null または Blank でないこと
- 条件: 手順2で取得したユーザーの手順2で取得したユーザーの
- レコードの更新（メッセージングユーザーの更新）：手順3が True の場合
- オブジェクト: メッセージングユーザー (MessagingEndUser)
- 更新条件:
Idが 手順1で取得したMessagingEndUserIdと一致する - 更新する項目:
ContactId（取引先責任者ID）に、手順2で取得したユーザーのContactIdを割り当てる
Step 7: 動作確認
それでは最後に動作確認です。実際にカスタマーユーザーにログインしてチャットを開始してみましょう。
まとめ
LWRサイト特有の制約により少し工夫が必要ですが、ヘッドレスLWCとPre-Chat APIを活用することで、シームレスにログインユーザーのセッション情報をオムニチャネルフローへ渡すことが可能です。ぜひご自身の環境でも試してみてください。
参考URL
オムニチャネルフローでの事前チャット値の対応付け
エクスペリエンスビルダーサイトでの拡張 Web チャットリリースの設定
事前チャット API を使用したエクスペリエンスサイトのサービス担当者への顧客情報の引き渡し
Hidden Pre-Chat in Enhanced Web Chat
読者の声