1. Feature Overview

The "User List" is the user-profile center scoped to a single Agent, used by operators and developers to view:

• Which end-users have had meaningful interactions with this Agent;
• Each user's identity (userId / anonymous ID);
• The number of key events each user has produced;
• Each user's activity timestamps (first contact, last active).
• For more on the user system, see: User Overview.

Entry point: Developer Console → enter an Agent → User Manage → Users.

2. User List Rules

Core rule: Only users who have produced at least one "key event" within this Agent will appear in the user list.

2.1 How users enter the list

The system maintains a "User List". There are two categories of trigger points for entering the list:

In other words, a visitor who only sent messages but did not trigger any key event will not appear in the user list. Only when the LLM extracts at least one key event from the conversation, or a key event is manually created via API/UI, does the user become "exposed" to the operations view.

2.2 Why list users by key event

Key events are factual fragments deemed to have business value, extracted semantically from conversation content (e.g. "withdrawal", "complaint", "dispute", "account opened"). Using "has produced a key event" as the listing criterion ensures:

• The list focuses on users who actually have business value, avoiding noise from one-off probing visitors;
• Columns like "key event count" and "last active" on user rows are comparable;
• Subsequent operations actions (marking, follow-up calls) have clear event anchors.

2.3 How key events are produced

Key events come from three triggers:

• REALTIME: triggered automatically after each new message in a session;
• SCHEDULED: re-extracts historical sessions on a recurring schedule;
• MANUAL: click "Extract" manually on the conversation detail page.

The extraction process is performed by the LLM according to the Agent's configured "event type dictionary" and business rules, and outputs four kinds of operations: CREATE / UPDATE / MERGE / DELETE.

Therefore, if you expect an Agent's user list to show more users, first confirm:
① whether the Agent has key-event extraction enabled;
② whether the event type dictionary covers the business scenarios you care about.

3. Identity: userId vs Anonymous ID

3.1 Field definitions

3.2 Priority rule

When the system locates "the same user", it follows:

If userId exists, use userId; if no userId, fall back to AnonymousId.

The "User Identity" column in the UI follows the same rule: prefer userId, otherwise show AnonymousId, with displayName (nickname) as a subtitle.

3.3 Relationship: upgrading from anonymous to logged-in

A typical end-user lifecycle:

                      
                      Visitor (only anonymousId) ──login/register──▶ Registered user (with userId)

                    

The platform provides bindUserId(botId, anonymousId, userId) for identity upgrade:

• If this userId does not yet exist under this Agent:
  • Write userId directly onto the original anonymous profile;
  • The original primaryAnonymousId and the anonymous-ID list are kept; historical key events continue to belong to the same profile.
• If this userId already exists under this Agent:
  • Merge all anonymousIds of the current anonymous profile into the existing logged-in user profile;
  • Delete the anonymous profile;
  • This delivers the experience of "anonymous browsing first → log in to an existing account → history merged".

Therefore, a user row in the list may have gone through: ① multiple anonymous IDs (cookie clearing / cross-device), ② finally bound to the same userId. The count badge in the "Anonymous ID" column is anonymousIds.length.

3.4 How key events are attributed to users

Key event entities (c_bot_event) also carry userId and anonymousId fields. When querying events in the user detail drawer, the matching rule is:

• When the user already has a userId: only query events where event.userId == userId;
• When the user only has an anonymous ID: query events where event.userId is missing AND event.anonymousId == primaryAnonymousId.

This ensures: upgraded registered users see all events under their userId; un-upgraded anonymous users only see events under their own anonymous identity, avoiding incorrect aggregation.

4. Time fields: First Contact vs Last Active

4.1 Field definitions

4.2 Write rules

• First Contact: written only once, when the user list entry is first created — never changes afterward. Think of it as "the starting point of this user's relationship with this Agent."
• Last Active: refreshed to the current time whenever any of these happens:
  • The user sends a message in this Agent;
  • A new key event is produced for this user;
  • A key event status changes;
  • Contact info (phone/nickname) is backfilled.

4.3 Business meaning

4.4 Default sort

The user list is sorted by Last Active descending by default — the most recently active users appear first.
Both time columns support clicking the header to sort numerically.

5. Column overview

6. Usage Guide

6.1 Searching for users

The keyword search box at the top of the page supports four kinds of matching (any one hit is enough):

Note: userId / anonymous ID do not support fuzzy queries — the full value must be entered.
Display name and phone support fuzzy queries.

6.2 Viewing a user's key events

Clicking the number in the "Key Events" column on a user row (or "View" at the end of the row) opens a right-side drawer that paginates events under these conditions:

• User scope: filtered by userId or anonymous ID per section 3.4;
• Secondary filters supported: event category, status, keyword (regex on event summary);
• Default sort is by event time descending.

Columns in the event drawer: event category, event summary, status, priority, confidence, update time.

6.3 Values for status, priority, confidence

6.4 Common operations actions

• New user follow-up: filter users whose first-contact time is within the last N days;
• Dormant user reactivation: combine with key event categories to filter users who had high-value actions but are no longer active;
• Open-event punch list: open the user detail drawer and filter by "Status = Pending / In Progress", then bulk follow-up.

7. FAQ

Q1: I see a user who sent many messages on the front end, but I can't find them in the user list.
A: The user list only shows "users who have produced key events". If this Agent does not have key-event extraction enabled, or the extraction result is empty (the message content does not match any configured event type), the user will not enter the list. Check the Agent's "Key Event Extraction" toggle and event-type dictionary. Conversations in the DevSpace Debug area are also not used to extract key events and will not show in the user list.

Q2: Why is the same real user sometimes shown as an anonymous ID and sometimes as a userId?
A: Before login, the SDK generates an anonymous ID for the session; after login, the integrator must pass in a business-side userId. The system uses bindUserId to merge the anonymous profile into the userId profile, so what you see in the list afterwards is the userId row; the original anonymous ID is preserved in the anonymousIds list for traceability.

Q3: "Last Active" doesn't match the most recent time in the conversation/message tables.
A: The profile is the source of truth. Last Active is refreshed at four kinds of points: message arrival, event creation, event status change, and contact info update; if there's a discrepancy, it usually comes from a non-standard path (e.g., offline import).

Q4: Can I modify "First Contact"?
A: No. This field is persisted only at first creation; no subsequent update will overwrite it.

Q5: What's the relationship between the user list and the conversation list?
A: The conversation list (in conversationId dimension) records each conversation; the user list (in userId / anonymousId dimension) is the per-person aggregation above conversations. One user can have multiple conversations; a key event must belong to one conversation and must belong to one user profile.