Chat

Session Management

A chat session is the container for a conversation: its messages, its variables, and its place in your reporting. Getting persistence right is the difference between a helpful assistant and one that forgets the customer every time they click a link.

How sessions are created

The widget creates a session on the visitor's first message, not on page load, so browsing your site never generates billable sessions. The session ID is stored in local storage under katexs.session and sent with every subsequent request.

Event	Session behaviour
Page reload or in-site navigation	Same session resumes with full history.
New tab, same browser	Same session — local storage is shared per origin.
Idle past the inactivity window	Session closes and is written to Call Logs.
Visitor clicks End chat	Session closes immediately with outcome tag ended_by_user.
Different device or browser	New session, unless you link identities (below).

Lifetimes

Two timers govern a session. The inactivity window closes a quiet conversation; the maximum lifetime caps even an active one so transcripts stay reviewable. Both are set per agent in Creator → Deploy.

yaml

session:
  inactivity_minutes: 30      # silence before auto-close
  max_lifetime_hours: 24      # hard cap regardless of activity
  resume_window_days: 7       # how long a closed session can be reopened
  storage: local              # local | cookie | none

Set storage to none for kiosks and shared terminals. The session then lives only in memory and disappears when the tab closes.

Cross-device continuity

To follow a customer from laptop to phone, attach a stable identity. When you call identify() with the same id, Katexs links the sessions under one contact and the agent can reference the earlier conversation.

Katexs.identify({
  id: "usr_812",                 // stable, from your own system
  email: "dana@example.com",
  signature: serverGeneratedHmac // required when verified identity is enabled
});

Enable verified identity in Creator when the agent can reveal account data. Katexs then rejects any identify() call without a valid HMAC computed server-side with your workspace secret, so a visitor cannot claim to be another customer by editing the page.

// Server-side, never in the browser
import { createHmac } from "crypto";
const signature = createHmac("sha256", process.env.KATEXS_IDENTITY_SECRET)
  .update("usr_812")
  .digest("hex");

Resuming a session yourself

If you manage storage in your own app — a native mobile shell, for example — pass the session ID explicitly. Any session within the resume window reopens with its history and variable bag intact.

Katexs.resume("sess_3fa91c04");
const id = Katexs.sessionId();       // persist this yourself
Katexs.reset();                      // abandon and start clean

Sessions in reporting

One row per session — Closed sessions appear in Data → Call Logs alongside voice calls, filterable by channel.
Webhooks on close — session.ended fires with the transcript, variables, and outcome tag — the same shape as call.ended.
Handoffs keep the ID — Transferring to a human does not close the session, so the full thread stays in one record.

Webhook events Variable substitution