Sessions & identity
How the KonvoAI widget remembers a visitor across reloads, tabs, and return visits.
The widget keeps just enough state in the browser to recognize a returning visitor and reconnect them to their conversation, while keeping the actual message history on the server. This page explains what persists, where, and for how long — so you can reason about what a visitor sees when they come back.
The two pieces of identity
There are two distinct identifiers, and they live in different places on purpose.
Visitor identity — persistent
On first load the widget generates a random visitor identifier and stores it in
localStorage. Because it's in localStorage, it:
- survives closing the tab and the browser, and
- is shared across all tabs on the same site.
This identifier is what threads a returning visitor's conversations together. As long as it's present, the widget can reload the visitor's past messages and continue the same conversation.
Session token — short-lived
After the browser-verification step, the widget receives a short-lived session
token and keeps it in sessionStorage, scoped to the specific channel. Because
it's in sessionStorage, it:
- lives only for the current tab, and
- expires on its own, after which the widget transparently re-verifies and gets a fresh one.
You don't manage this token; it's an implementation detail of staying connected. It's mentioned here only so the storage behavior isn't a surprise.
What persists, at a glance
| What | Storage | Scope | Survives reload | Survives tab close |
|---|---|---|---|---|
| Visitor identity | localStorage | Per site (all tabs) | Yes | Yes |
| Session token | sessionStorage | Per tab, per channel | Yes (same tab) | No |
| Email-prompt state | sessionStorage | Per tab | Yes (same tab) | No |
| Conversation history | Server-side | Tied to visitor identity | Yes | Yes |
All client-side keys are namespaced under konvoai:widget:* so they're easy to
identify and won't collide with your own storage.
What a returning visitor sees
Same tab, later in the session
The visitor's token is still valid, so the widget reconnects immediately and shows their conversation right where they left off.
New tab or after a reload
The session token may be gone, but the persistent visitor identity is still in
localStorage. The widget re-verifies in the background and reloads the same
conversation history.
A return visit days later
As long as the visitor's localStorage is intact, they're recognized and their
past conversation is restored — even though message history was never kept in
the browser.
When a visitor is treated as new
A visitor starts fresh — a new identity, no past conversation visible — whenever the persistent identifier isn't available:
- They clear site data / cookies or use the browser's "forget this site."
- They visit in a private/incognito window (and again each time they reopen one).
- They switch to a different browser or device.
- Their browser blocks storage for the page (some strict privacy or embedded-webview contexts).
Identity is per-origin
Browser storage is scoped to a single origin (scheme + domain). A visitor
recognized on shop.example.com is a different visitor on
help.example.com or example.org. The widget does not
share identity across domains.
Linking a known email
The visitor identity above is anonymous by design. If you know who the visitor is, attach their email so conversations are tied to a real person rather than just a browser:
- Set
window.__konvoai_widget_emailfrom your page, or - let the visitor enter it in the chat's email prompt (when enabled for the channel).
Providing an email doesn't replace the visitor identifier — it enriches it, so the same person is recognizable even if they later clear storage on one device and start a fresh session on another.
A note on “logging out”
There's no visitor-facing logout, because the widget never logs anyone in — the visitor identity is anonymous. Clearing site data is the visitor's own reset. Conversation history they had under the old identity stays on the server; it's simply no longer linked to that browser.