Skip to main content

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):

StatusMeaning
activeVisitor is still on the site — appears in Live Sessions
finalized (a.k.a. stale)Visitor left or went idle; queued for analysis
analyzingThe recording-analysis worker has the job
analyzedReplay + analysis available in Recorded Sessions
failedAnalysis 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 / fieldWhereEffect
SubscriptionModel.remaining_live_session_viewsSubscription / planMeters 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_permissionsCompany configGates whether an admin may call-in to a live visitor (verify exact key name)
Verified badgeAlways onRenders whenever identity_trust === 'verified' (the verified_visitor_badge_enabled gate was removed 2026-09-25)
Bot detectionAutomaticNo configuration; Suspected/Confirmed Bot badges appear automatically
iframe companion scriptCustomer siteEnables 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 (behaviour category) 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-block are masked; with recording_masking_v2 every 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_visitor tool) pushes an on-demand auto-trigger to a live visitor: backend POST /user-session/:_id/engage (+ GET /user-session/:_id/engage-status) → ms-communication nox-auto-engage-message socket → widget. Delivery is confirmed by a receipt chain: widget ai-auto-trigger-delivery reports displayed/blocked_reason, ms-comm broadcasts visitor-engage-result to admins and posts backend POST /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 the nox_live_at field).
  • Bot traffic is hidden by default. The list filters out isBotSession rows (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-comm 7813cfd): 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 (frontend 0ab6c8b0). See ms-sessions → Presence.
  • Tabs no longer go "stale" while live — ms-sessions fd76e75 takes the newest of last_beat/last_event_time/ready_time and heartbeats local tabs even without Redis; before, a single-pod/no-Redis setup marked every tab offline TAB_STALE_MS after widget-ready.
  • Large live events go by pointer (ms-sessions c2e402e, 4283459, 9e165d5; frontend 862da0f2). 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, any user-event / HTTP send-event whose event string is ≥ LIVE_EVENT_OFFLOAD_CHARS (32 KB) is parked at live-event:<128-bit hex ref> (JSON-encoded — the LZ string holds lone UTF-16 surrogates Redis would corrupt; TTL LIVE_EVENT_TTL_SECONDS, 120 s) and broadcast as { ...rest, event_ref, event_size }. The dashboard (useLiveSocket withResolvedEvent) fetches GET <ms-sessions>/live-event/:ref (any pod; ?format=utf16le returns 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 at live-latest:<room>:<tab>, and a viewer that saw snapshot-sent without the snapshot emits request-latest-event → user-event + latest-event { found, seq } to that socket only. The adapter stream maxLen stays 10000 (SOCKET_ADAPTER_STREAM_MAX_LEN) because it also backs connectionStateRecovery.
  • 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 Redis session_sockets and page views open forever. syncPresence asks every pod (fetchSockets) on disconnect and in ActiveSessionJob, which retires only sessions with no live socket (2-min idle grace); a reconnect resumes its page view by handshake file_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) — beforeunload fires for a close, a link click and a reload alike, and iOS Safari never fires it. The widget now emits visitor-navigating on 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 on pagehide and reconnect on a bfcache restore.
  • Backgrounded mobile visitors (2ceed995e) — mobile browsers freeze a hidden page without pagehide. The widget reports visitor-hidden / visitor-visible on mobile; backend SocketService disconnects a socket hidden for HIDDEN_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-sessions f6f8942, frontend 603c0e75 / 58662c61): one snapshot upload in flight (ms-sessions acks send-event); snapshot requests made during an upload are served by it; snapshot-sent carries seq + snapshot_ts and the stored snapshot is replayed only for that exact pair; the widget stream stops only when its last viewer leaves (leave-live-session + live-viewers room counted across pods, 3 s leave / 15 s disconnect grace; a desktop build's backend stop-live-session is forwarded via legacy-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); a not-streaming NACK 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 with UNSAFE_replayCanvas: true, which sandboxed the iframe with allow-scripts allow-same-origin, so visitor HTML could run in the dashboard. Now false (both recorders use recordCanvas: false, nothing lost); the chat-list preview strips HTML via DOMParser.
  • View Chat with no chat — old empty per-visit chats are archived, so handleViewChat calls getUserSessionChat first; 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_views for 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, nested lead_score), session_files (recording_status, chunk metadata). SubscriptionModel holds remaining_live_session_views.
  • Presence: Redis session_tabs:{user_session_id} registry; exposed via GET /internal/knox/presence/snapshot and /internal/knox/presence/visitor.
  • Frontend: LiveSessionsView + frontend/src/components/SessionPlayer/ with useLiveReplayer.
  • Engage: backend UserSessionController@engageVisitor / @engageStatus (userSessionRoutes.js), receipt at POST /internal/engage-receipt (internalKnoxRoutes.js); ms-ai tool knox_engage_visitor.
  • Nox tool: knox-presence returns a live snapshot (concurrency, top countries/pages, identified-vs-anonymous, score distribution); per-visitor entries now include person_id (verified preferred) and a resolved display_name (KnoxPresenceController).
  • Subsystems: Session Recording, Identity Graph.