一、機能概要
「ユーザー一覧」は単一の Agent（エージェント）配下のユーザープロファイルセンターであり、運用担当者および開発者が以下を確認するための画面です。
- どのエンドユーザーがその Agent と意味のあるインタラクションを行ったか
- 各ユーザーの ID 識別子（userId / 匿名 ID）
- 各ユーザーが生成した重要イベントの件数
- 各ユーザーのアクティブ時刻（初回接触、最終アクティブ）
- ユーザー体系に関する詳細情報は次を参照：ユーザー概要
アクセス経路：開発者コンソール → 任意の Agent に入る → ユーザー管理（User Manage） → ユーザー（Users）。
二、ユーザー一覧のルール
コアルール：その Agent 内で少なくとも 1 件の「重要イベント」を生成したユーザーのみがユーザー一覧に表示されます。
2.1 ユーザー一覧の生成方法
システム内には「ユーザー一覧」が存在し、リスト入りのトリガーは以下の 2 種類があります。
| トリガー | 一覧に表示されるか | 説明 |
|---|---|---|
| エンドユーザーがその Agent にメッセージを送信 | 表示されない | 後続でイベントが発生した場合に関連付けできるよう保証されるのみ。単独でユーザーを表示させることはない |
| 重要イベント抽出後に新規イベントが書き込まれる | 表示される、プロファイル内のイベント件数 +1、ユーザーが一覧に登場 | 同時に最終アクティブ時刻などのフィールドも更新される |
| イベントステータス変更 | 一覧に既存のユーザーが更新される | — |
| 連絡先情報の補完 | 一覧に既存のユーザーに対し電話番号、表示名などを補完 | — |
つまり、メッセージを送っただけで重要イベントを一切トリガーしていない訪問者は、ユーザー一覧に表示されません。LLM が対話から少なくとも 1 件の重要イベントを抽出するか、API/UI 経由で重要イベントが手動作成された場合にのみ、そのユーザーが運用ビューに「露出」されます。
2.2 なぜ重要イベントを基準にするのか
重要イベントとは、システムが会話内容に対して意味解析を行い、業務的価値があると判断した事実の断片です（例：「出金」「クレーム」「異議申し立て」「口座開設成功」など）。「重要イベントが発生した」ことを一覧入りの基準とすることで、以下が保証されます。
- 一覧が真に業務価値のあるユーザーに集約され、一回限りの試し利用ユーザーのノイズに埋もれない
- ユーザー行の「重要イベント数」「最終アクティブ」などの列が比較可能になる
- 後続の運用アクション（処理マーキング、アウトバウンド連絡）に明確なイベントアンカーが存在する
2.3 重要イベントの生成方法
重要イベントは 3 種類のトリガーから生成されます。
- REALTIME（リアルタイム）：会話で新しいメッセージが発生するたびに自動的に抽出をトリガー
- SCHEDULED（定時）：スケジュールに従って過去会話を周期的に補抽出
- MANUAL（手動）：会話詳細ページで手動で「抽出」ボタンをクリック
抽出処理は LLM が現在 Agent に設定された「イベントタイプ辞書」と業務ルールに従って分類を行い、CREATE / UPDATE / MERGE / DELETE の 4 種類の操作を出力します。
したがって、ある Agent のユーザー一覧により多くのユーザーを表示させたい場合は、まず以下を確認してください。
① その Agent で重要イベント抽出が有効になっているか
② イベントタイプ辞書が対象とする業務シーンを網羅しているか
三、ID 識別子：userId と匿名 ID
3.1 フィールド定義
| フィールド名 | 意味 | 生成元 |
|---|---|---|
userId |
ユーザー ID、最上位の識別子。導入側（開発者）が自身の業務システム（アカウント体系 / CRM）から渡す | 開発者側 |
anonymousIds |
そのユーザーが関連付けたすべての匿名 ID リスト。デバイス間 / 昇格マージに使用 | システム管理 |
3.2 優先度ルール
システムは「同一ユーザー」を特定する際に以下のルールに従います。
userIdがある場合はuserIdを優先し、userIdがない場合はAnonymousIdにフォールバックする。
UI 上の「ユーザー識別子」列の表示も同じルールに従います。優先的に userId を表示し、なければ AnonymousId を表示し、displayName（ニックネーム）をサブタイトルとして表示します。
3.3 両者の関係：匿名からログインへの昇格
エンドユーザーの一般的なライフサイクルは次の通りです。
訪問者（anonymousId のみ保持） ──ログイン/登録──▶ 登録ユーザー（userId 付与）
プラットフォームは bindUserId(botId, anonymousId, userId) を提供し、ID 昇格に使用します。
- 当該
userIdが当該 Agent 配下にまだ存在しない場合：- 元の匿名プロファイルにそのまま
userIdを書き込む - 元の
primaryAnonymousIdおよび匿名 ID リストは保持され、過去の重要イベントは引き続き同じプロファイルに帰属する
- 元の匿名プロファイルにそのまま
- 当該
userIdが当該 Agent 配下に既に存在する場合：- 現在の匿名プロファイルが持つすべての
anonymousIdsをログイン済みユーザープロファイルにマージする - 匿名プロファイルを削除する
- 「先に匿名アクセス → 後で旧アカウントにログイン → 履歴マージ」という体験を実現する
- 現在の匿名プロファイルが持つすべての
したがって、一覧で見えるあるユーザー行は、① 複数の匿名 ID（cookie のクリア / クロスデバイス）、② 最終的に同じ
userIdにバインド、を経ている可能性があります。「匿名 ID」列の数量バッジはanonymousIds.lengthを示しています。
3.4 重要イベントがどのユーザーに帰属するか
重要イベントエンティティ（c_bot_event）にも userId と anonymousId フィールドが保持されます。ユーザー詳細ドロワーでイベントを照会する際のマッチングルールは以下の通りです。
- ユーザーが既に
userIdを持つ場合：event.userId == userIdのイベントのみを照会 - ユーザーが匿名 ID のみを持つ場合：
event.userId が存在せず、かつ event.anonymousId == primaryAnonymousIdのイベントを照会
これにより、昇格後の登録ユーザーは userId 配下のすべてのイベントを参照でき、未昇格の匿名ユーザーは自身の匿名次元のイベントのみを参照し、誤って集計されることがありません。
四、時間フィールド：初回接触 vs 最終アクティブ
4.1 フィールド定義
| 日本語 | 型 | 意味 |
|---|---|---|
| 初回接触 | ミリ秒タイムスタンプ | 当該ユーザープロファイルが本 Agent で初めて作成された時刻 |
| 最終アクティブ | ミリ秒タイムスタンプ | 当該ユーザープロファイルが直近で接触/変更された時刻 |
4.2 書き込みルール
- 初回接触：ユーザー一覧で初回作成時に 1 度だけ書き込まれ、以降は永久に変更されません。「当該ユーザーと本 Agent の出会いの起点」と理解できます。
- 最終アクティブ：以下のイベントが発生するたびに現在時刻に更新されます。
- ユーザーが当該 Agent にメッセージを送信した
- 当該ユーザーが新しい重要イベントを生成した
- 重要イベントのステータスが変更された
- 連絡先情報（電話番号 / ニックネーム）が補完された
4.3 業務的な意味
| シーン | 参照すべきフィールド |
|---|---|
| ユーザー獲得 / 新規ユーザー分析、リテンション分類 | 初回接触 |
| アクティブ度ソート、フォロー優先度、リスト更新 | 最終アクティブ |
| 長期間訪問のない「休眠ユーザー」のフィルタリング | 最終アクティブ（昇順または時間ウィンドウでフィルタリング） |
4.4 一覧のデフォルトソート
ユーザー一覧はデフォルトで 最終アクティブ時刻の降順で表示されます。最近動きがあったユーザーが最上位に表示されます。
2 つの時間列はいずれも列ヘッダーをクリックして数値ソートが可能です。
五、一覧フィールド一覧
| 列 | 値のフィールド | 説明 |
|---|---|---|
| ユーザー識別子 | userId または AnonymousId（userId 優先） + displayName サブタイトル |
行タイトル。クリックで重要イベントドロワーがポップアップ |
| 匿名 ID | anonymousIds（数量バッジ + マウスホバーで一覧表示） |
当該ユーザーがバインド/マージした匿名 ID 数を反映 |
| 重要イベント | totalEventCount |
累計イベント数。クリックでイベントビューに入る |
| 最終アクティブ | lastActiveTime |
第 4 章を参照 |
| 初回接触 | firstContactTime |
第 4 章を参照 |
六、使用ガイド
6.1 ユーザー検索
ページ上部のキーワード検索ボックスは 4 種類のマッチングをサポートします（いずれかにヒットすれば検出）。
| フィールド | マッチング方式 |
|---|---|
userId |
完全一致 |
anonymousId |
完全一致 |
displayName |
正規表現あいまい一致 |
phone |
正規表現あいまい一致 |
注意：userId / 匿名 ID はあいまい検索をサポートしません。完全な値を入力する必要があります。
表示名と電話番号はあいまい検索をサポートします。
6.2 ユーザーの重要イベントを参照
ユーザー行の「重要イベント」列の数字（または行末の「表示」）をクリックすると、右側ドロワーが以下の条件でイベントをページネーション取得します。
- ユーザー範囲：3.4 節のルールに従い
userIdまたは匿名 ID でフィルタリング - 二次フィルタリング対応：イベント分類、ステータス、キーワード（イベント要約に基づく正規表現）
- デフォルトでイベント時刻の降順で表示
イベントドロワーの列：イベント分類、イベント要約、ステータス、優先度、信頼度、更新時刻。
6.3 ステータス、優先度、信頼度の値
| 次元 | 選択可能な値 |
|---|---|
ステータス (status) |
未処理 PENDING / 処理中 IN_PROGRESS / 解決済み RESOLVED / 終了 CLOSED |
優先度 (priority) |
低 LOW / 中 MEDIUM / 高 HIGH / 緊急 CRITICAL |
信頼度 (confidence) |
低 LOW / 中 MEDIUM / 高 HIGH |
6.4 一般的な運用アクション
- 新規ユーザーフォロー：直近 N 日以内に初回接触したユーザーをフィルタリング
- 休眠ユーザー復活：重要イベント分類と組み合わせて、過去に高価値アクションを起こしたが現在非アクティブなユーザーを抽出
- 未処理イベントリスト：ユーザー詳細ドロワーで「ステータス = 未処理 / 処理中」でフィルタリングし、まとめてフォロー
七、よくある質問（FAQ）
Q1：あるユーザーがフロントエンドで多数のメッセージを送信しているのを見たが、ユーザー一覧で検索できない？
A：ユーザー一覧は「重要イベントが発生したユーザー」のみを表示します。当該 Agent が重要イベント抽出を有効にしていない場合や、抽出結果が空（メッセージ内容が設定済みのイベントタイプにヒットしない）の場合、そのユーザーは一覧に登場しません。Agent の「重要イベント抽出」のスイッチとイベントタイプ辞書を確認してください。開発スペース-Debug 内の対話も重要イベント抽出には使用されず、ユーザー一覧にも表示されません。
Q2：同じ実在ユーザーがあるときは匿名 ID、あるときは userId として表示されるのはなぜ？
A：エンドユーザーがログイン前は SDK が生成した匿名 ID で会話を行います。ログイン後、導入側は業務側の userId を渡す必要があります。システムは bindUserId で匿名プロファイルを userId プロファイルにマージし、一覧で後続に表示されるのは userId の行になります。元の匿名 ID は anonymousIds リストに保持され、追跡可能です。
Q3：「最終アクティブ」が会話/メッセージテーブルの最新時刻と一致しない？
A：プロファイルが基準です。最終アクティブ時刻は、メッセージ到着、イベント作成、イベントステータス変更、連絡先情報更新の 4 つのタイミングで更新されます。差異が出る場合、多くは何らかの操作が標準パスを通らなかったため（例：オフラインインポート）です。
Q4：「初回接触」は変更可能ですか？
A：不可。このフィールドは初回作成時にのみ書き込まれ、以降のいかなる更新でも上書きされません。
Q5：ユーザー一覧と会話一覧の関係は？
A：会話一覧（conversationId 次元）は各対話を記録します。ユーザー一覧（userId / anonymousId 次元）は会話の上位に位置する人ベースの集計です。1 ユーザーは複数の会話に対応可能です。1 件の重要イベントは必ず 1 つの会話に帰属し、必ず 1 つのユーザープロファイルに帰属します。