Session Settings
A session is the container for one user's conversation with an agent. These settings control how long sessions stay alive, when they expire, and what extra data you can attach to them.
Session types
| Type | How it starts | Default inactivity expiry |
|---|---|---|
| Anonymous | Widget opens automatically - no user identity required | 30 minutes |
| Signed | Your server creates a session with an externalUserId | 480 minutes (8 hours) |
Configurable limits
| Setting | Default | Description |
|---|---|---|
| Anonymous session expiry | 30 min | Inactivity window before an anonymous session is marked expired. Resets on each message. |
| Signed session expiry | 480 min | Same as above for signed sessions. |
| Max session duration | 60 min | Hard cap on total session wall-clock time, regardless of activity. |
| Max messages per session | 50 | Maximum number of messages (user + assistant combined) before the session stops accepting new messages. |
Session status lifecycle
Sessions move through a well-defined set of states:
| Status | Meaning |
|---|---|
active | Session is open and accepting messages. |
idle | No messages recently - within the expiry window but not yet expired. |
expired | Inactivity or hard duration limit reached. No new messages accepted. |
closed | User or your server explicitly closed the session. |
escalated | User requested human support. The session is linked to an escalation ticket. |
blocked | Session was flagged and suspended - typically by a rate limit or policy violation. |
Session metadata
You can attach arbitrary key/value metadata to a session when it is created. This is useful for passing context from your application - for example the user's locale, a brand or market code, or the current page URL. Metadata is available to action inputs via the session metadata input type.
// Example metadata passed at session init
{
"locale": "en-GB",
"brandCode": "MAIN",
"market": "UK",
"currentPage": "/checkout"
}Metadata is sanitised before storage: nesting is limited to prevent injection attacks, and very large payloads are rejected. Keep metadata flat and concise.
Privacy-preserving fingerprinting
Bounds stores hashed versions of the user's IP address and user agent string for analytics and abuse detection. The raw values are never stored. Origin domain and referrer are stored in plain text.