Live Sessions
Audience: Sales · Support · QA · Engineering · Management · Where in app: Live Sessions (/live-sessions) · Plan availability: All plans (live-session view count is metered — see Plan & limits)
Live Sessions is the real-time view of everyone on a customer's website right now. Each row is one active visitor: the page they're on, how long they've been browsing, who they are (if we know), their lead score, and their location. An admin can watch the visitor's screen as it happens, start a chat, place a call, or just monitor. It's the surface sales and support teams live in when they want to catch a hot visitor mid-visit instead of chasing them afterwards.
What it does
- Lists every visitor with an active session, updating automatically as people arrive and leave.
- Shows, per visitor: current page URL + title, time on page, total time on site, pages visited, country/city, device + browser/OS, traffic source, IP, and the running lead score.
- Resolves identity inline: a verified visitor shows their name; an anonymous visitor whose network resolves to a known company (via B2B enrichment) shows the company name instead of "Guest User"; an unconfirmed match shows a Suspected badge.
- Lets an admin watch the screen in near-real-time (rrweb live mode), start a chat, start a call, or jump straight to an existing conversation.
- Flags bot traffic (Suspected Bot / Confirmed Bot) so teams don't waste time engaging crawlers.
How it works
The widget streams rrweb DOM events to ms-sessions over Socket.IO, keyed by company_id + user_session_id. While the visitor is browsing, the session's recording_status is active and they appear on the live list.
Recording lifecycle (session_files.recording_status):
| Status | Meaning |
|---|---|
active | Visitor is still on the site — appears in Live Sessions |
finalized (a.k.a. stale) | Visitor left or went idle; queued for analysis |
analyzing | The recording-analysis worker has the job |
analyzed | Replay + analysis available in Recorded Sessions |
failed | Analysis errored — see retry/error |
Live replay. Clicking a row opens a player in rrweb "live" mode — the same DOM event stream that later becomes the recording, rendered as it arrives. The dashboard uses frontend/src/components/SessionPlayer/ with useLiveReplayer. There is no extra capture cost; live and recorded replay share one stream.
Presence. "Who is live" is answered from a cross-pod Redis registry (session_tabs:{user_session_id}, ~90s TTL, renewed every ~30s) so any ms-sessions pod can answer the question. This is the same presence layer ms-communication and Nox read. See ms-sessions › Presence and Session Recording.
Identity resolution on the list. Names come from the identity graph. If the visitor is verified, their name shows. Otherwise the row shows "Anonymous visitor" / "Guest User" with whatever signals exist (location, source, current page) — or a resolved company name if B2B enrichment matched their IP. See Lead Intelligence.
Multi-tab tracking. A visitor with several tabs open on the site shows all open tabs under one session entry — handled automatically via the presence registry.
Real-time per-session stats: current URL + page title, time on current page, total time on site, pages visited this session, country/city, device type, any active chat/call, and the running lead score.
Configuration & options
| Setting / field | Where | Effect |
|---|---|---|
SubscriptionModel.remaining_live_session_views | Subscription / plan | Meters how many distinct live sessions can be watched per period. Each unique session viewed counts once. Higher tiers are effectively unlimited. (verify exact per-tier numbers) |
take_over_permissions | Company config | Gates whether an admin may call-in to a live visitor (verify exact key name) |
| Verified badge | Always on | Renders whenever identity_trust === 'verified' (the verified_visitor_badge_enabled gate was removed 2026-09-25) |
| Bot detection | Automatic | No configuration; Suspected/Confirmed Bot badges appear automatically |
| iframe companion script | Customer site | Enables recording to span an embedded iframe the customer controls (see edge cases) |
For QA/support: a visitor not appearing live almost always means the widget isn't streaming (script missing, blocked, or socket failing) — check that the widget is installed and the session shows recording_status: active.
Behaviors & edge cases
- Verified vs Suspected. A Suspected (amber) badge means the identity graph thinks it recognises the visitor by IP, device, or both, but they haven't confirmed it this visit. It is a hint, not a fact — do not greet the visitor by that name. A Verified badge means the AI is working with full cross-session history.
- Anonymous company resolution. "Acme Corp" appearing instead of "Guest User" comes from reverse-IP B2B enrichment (Snitcher, with Apollo for person-level) — it identifies the network/company, not necessarily the specific person. Naming tiers: self-provided → suspected → Apollo person → Snitcher company (business type) → Snitcher domain (⚠, non-business). See Lead Intelligence caveats.
- Consent gating. For tenants with consent gating enabled, the loader doesn't initialize rrweb/live-view (
behaviourcategory) until the visitor consents — a non-consented visitor cannot be watched live; a mid-session grant starts capture forward-only. - Location source. City/country comes from B2B company data when available, falling back to IP geolocation; the source is tagged so a confident company HQ can be told apart from a best-guess IP lookup.
- Privacy / masking. Password fields and inputs marked
data-rrweb-blockare masked; withrecording_masking_v2every typed value is masked unless allowlisted (see GDPR & Privacy). Cross-origin iframes are not captured unless the iframe companion script is installed. Recordings are tenant-isolated. - Engage-visitor flow. An admin (Engage panel) or Nox (ms-ai
knox_engage_visitortool) pushes an on-demand auto-trigger to a live visitor: backendPOST /user-session/:_id/engage(+GET /user-session/:_id/engage-status) → ms-communicationnox-auto-engage-messagesocket → widget. Delivery is confirmed by a receipt chain: widgetai-auto-trigger-deliveryreportsdisplayed/blocked_reason, ms-comm broadcastsvisitor-engage-resultto admins and posts backendPOST /internal/engage-receipt. Engage bypasses the widget's heuristic auto-trigger suppressors, but hard blockers (tab hidden, user interacting, call in progress) still refuse with a reason. Liveness for engage = Redis heartbeat presence (backend/app/lib/sessionPresence.js; replaced thenox_live_atfield). - Bot traffic is hidden by default. The list filters out
isBotSessionrows (suspected_bot || is_bot); a filter toggle shows them. - Live-list accuracy. Backend
ActiveSessionJob(1 min) was reworked so stale sessions drop off promptly; mobile live view fixed for compressed rrweb frames (backend/public/live_session_for_mobile.js). - Mobile. Mobile sessions render via
live_session_for_mobile.js(touch events, orientation). A desktop admin can still watch them. - Company room requires an authorized dashboard user (2026-10-14, ms-sessions
9899eaf, ms-comm7813cfd): live page-URL / event broadcasts to the company room only reach sockets that handshake with a user JWT (auth.token) able to manage that company; widget sockets stay in their session room. The playground passes its owner token on ms-communication sockets (frontend0ab6c8b0). See ms-sessions → Presence. - Tabs no longer go "stale" while live — ms-sessions
fd76e75takes the newest oflast_beat/last_event_time/ready_timeand heartbeats local tabs even without Redis; before, a single-pod/no-Redis setup marked every tab offlineTAB_STALE_MSafter widget-ready. - Large live events go by pointer (ms-sessions
c2e402e,4283459,9e165d5; frontend862da0f2). Full rrweb snapshots (~1 MB) stalled 30 s+ or vanished on the Redis-streams Socket.IO adapter (every pod reads one shared stream) — "live session won't load". With Redis on, anyuser-event/ HTTPsend-eventwhoseeventstring is ≥LIVE_EVENT_OFFLOAD_CHARS(32 KB) is parked atlive-event:<128-bit hex ref>(JSON-encoded — the LZ string holds lone UTF-16 surrogates Redis would corrupt; TTLLIVE_EVENT_TTL_SECONDS, 120 s) and broadcast as{ ...rest, event_ref, event_size }. The dashboard (useLiveSocketwithResolvedEvent) fetchesGET <ms-sessions>/live-event/:ref(any pod;?format=utf16lereturns raw 2-byte units, ~40% smaller), skipping refs for a tab it isn't showing; a failed/expired fetch drops the event and the snapshot retry ladder re-asks the widget. Lost pointers: the latest pointer per room+tab is also kept atlive-latest:<room>:<tab>, and a viewer that sawsnapshot-sentwithout the snapshot emitsrequest-latest-event→user-event+latest-event { found, seq }to that socket only. The adapter streammaxLenstays 10000 (SOCKET_ADAPTER_STREAM_MAX_LEN) because it also backsconnectionStateRecovery. - Empty states — no live visitors: "No one's on your website right now — Visitors will appear here the moment they land."; a search with no hits: "No live sessions match your search" (
LiveSessionsList.vue,862da0f2). Chats list / Chats view fall back to Unknown User (was "Unknown Company") when a session has no name. - Presence follows live widget sockets on every pod (backend
639f151da, 2026-10-22). Deploys used to kill pods before their disconnect handler ran, leaving dead socket ids in Redissession_socketsand page views open forever.syncPresenceasks every pod (fetchSockets) on disconnect and inActiveSessionJob, which retires only sessions with no live socket (2-min idle grace); a reconnect resumes its page view by handshakefile_id(fresh view after 5 min); an SPA navigation ends the socket's previous page view; a heartbeat revives a session retired while still connected. Old data: the Close stuck page views maintenance job (/migrations+/admin/maintenance, also ends views that sat open >24 h at their start). - Closed tab vs navigation (
b27b5ec26) —beforeunloadfires for a close, a link click and a reload alike, and iOS Safari never fires it. The widget now emitsvisitor-navigatingon a same-site navigation (Navigation API, else link/form); a disconnect right after it waits 8 s for the next page's socket (settleVisitorDisconnect), any other disconnect settles at once. Sockets close onpagehideand reconnect on a bfcache restore. - Backgrounded mobile visitors (
2ceed995e) — mobile browsers freeze a hidden page withoutpagehide. The widget reportsvisitor-hidden/visitor-visibleon mobile; backendSocketServicedisconnects a socket hidden forHIDDEN_DROP_MS(30 s), which runs the normal offline path; the widget reconnects when visible again. - Viewer-detected departure (frontend
264fb68b) — when the ms-sessions snapshot probe reports no live tabs for a widget seen alive during this viewing, the store marks the session offline (badge, dot, "on site" count). A widget never seen alive is left to the backend (an empty registry can mean it is still starting). - Live streaming hygiene (backend
89a6eaf61/acb364cda, ms-sessionsf6f8942, frontend603c0e75/58662c61): one snapshot upload in flight (ms-sessions ackssend-event); snapshot requests made during an upload are served by it;snapshot-sentcarriesseq+snapshot_tsand the stored snapshot is replayed only for that exact pair; the widget stream stops only when its last viewer leaves (leave-live-session+live-viewersroom counted across pods, 3 s leave / 15 s disconnect grace; a desktop build's backendstop-live-sessionis forwarded vialegacy-stop-live-session); a newer snapshot heals a seq gap (idle visitors never sent the 20 events that force a flush, leaving the viewer blank); anot-streamingNACK holds the retry ladder while a background tab starts; the tab switcher shows while loading and the address bar follows the selected tab. - Replay iframe is script-free (frontend
61263b55) — live replay ran withUNSAFE_replayCanvas: true, which sandboxed the iframe withallow-scripts allow-same-origin, so visitor HTML could run in the dashboard. Nowfalse(both recorders userecordCanvas: false, nothing lost); the chat-list preview strips HTML viaDOMParser. - View Chat with no chat — old empty per-visit chats are archived, so
handleViewChatcallsgetUserSessionChatfirst; a 404 shows "No chat yet — use Chat to message this visitor" (the Chat panel creates the chat on the first message). - Recording widget load order (
7175e1dd5) — rrweb, lz-string and the live/recorded session scripts now load alongside the widget iframe instead of in front of it; a failed recording script no longer stops the widget rendering. - GDPR safe mode — EU/EEA/UK/CH (or unknown-country) visitors are not recorded or streamed until explicit consent; see GDPR & Privacy.
Plan & limits
- Live Sessions is available on all plans, but watching a live session draws down
remaining_live_session_viewsfor the billing period; higher tiers are unlimited. (verify per-tier view allotments) - Call-in from a live session depends on call permissions/availability for the account.
- B2B company resolution on anonymous visitors requires Lead Intelligence enrichment, which has its own plan gating and budget — see Lead Intelligence › Plan & limits.
Technical implementation
- Service:
ms-sessions—LiveSessionController,KnoxPresenceController(presence snapshot/visitor endpoints),SocketService(rrweb buffering). - Collections:
user_sessions(session lifetime, current URL, nestedlead_score),session_files(recording_status, chunk metadata).SubscriptionModelholdsremaining_live_session_views. - Presence: Redis
session_tabs:{user_session_id}registry; exposed viaGET /internal/knox/presence/snapshotand/internal/knox/presence/visitor. - Frontend:
LiveSessionsView+frontend/src/components/SessionPlayer/withuseLiveReplayer. - Engage: backend
UserSessionController@engageVisitor/@engageStatus(userSessionRoutes.js), receipt atPOST /internal/engage-receipt(internalKnoxRoutes.js); ms-ai toolknox_engage_visitor. - Nox tool:
knox-presencereturns a live snapshot (concurrency, top countries/pages, identified-vs-anonymous, score distribution); per-visitor entries now includeperson_id(verified preferred) and a resolveddisplay_name(KnoxPresenceController). - Subsystems: Session Recording, Identity Graph.
Related
- Recorded Sessions — replay and search past visits
- Per-Session Signals — what gets extracted from a recording
- Lead Scoring — the score shown on each row
- Lead Intelligence — anonymous → company resolution
- ms-sessions · Session Recording · Identity Graph