Skip to content

Anonymous sessions & sign-in promotion

A visitor should be able to start chatting before they sign in — and, when they do sign in, keep the conversation they already have. DioscHub treats anonymous sessions as first-class and promotes them in place on sign-in, so nothing is lost.

To let a visitor chat without an account, bind the connection with no identity — send identity: null (or omit it) on POST /auth/bind. That produces an anonymous binding. DioscHub resolves the anonymous Role’s feature flags for the connection and hands them to the widget when it signals ready.

The widget waits to be told its identity — including the anonymous one — before it starts a Session. Feature gating follows from this: the widget holds features closed until the bind delivers them, so an anonymous visitor sees exactly what the anonymous Role grants, never a signed-in default.

Anonymous-only embeds need no bind endpoint

Section titled “Anonymous-only embeds need no bind endpoint”

If your page never signs anyone in (a public site assistant, a marketing page), you can leave bindEndpoint out of the widget’s configuration. With no bind endpoint, the widget asks DioscHub for an anonymous binding over its own connection, and DioscHub binds the connection itself. The visitor gets the anonymous Role’s features, starter suggestions and commands (for example New Chat when the Role allows several sessions), exactly as if your backend had bound with identity: null.

DioscHub does this only when all of these hold:

  • the Assistant’s anonymous mode is enabled and the Assistant is active;
  • the Assistant has an active anonymous Role (DioscHub never falls back to another Role);
  • the deployment does not run in host-required scope mode.

Otherwise nothing is bound, and the widget reports a failed bind in the browser console, as it did before.

A binding made this way is the same as an anonymous bind from your backend: no identity, no forwarded auth, no REST token, the same origin check, rooms and anonymous session limits (per device and per IP, plus the bot-protection challenge). The widget’s request carries nothing DioscHub reads, so it can never claim an identity, a Role or credentials: asserting who a user is still takes your backend’s auth:bind key. A connection your backend has already bound to a user is never changed by it.

When you later add sign-in, add a bindEndpoint: from then on the widget calls your endpoint and DioscHub stops binding the page itself.

DioscHub limits how many new chats anonymous visitors can start on an Assistant, so that nobody can reset their per-session token budget by opening chat after chat:

LimitDefaultWhere to set it
New chats per browser5 per houranonymous Role dialog → Anonymous → Sessions per device; over the admin API anonymousConfig.sessionsPerDevice (0 turns it off)
New chats per network (client IP)60 per hourAdmin API only: anonymousConfig.sessionsPerIp on the anonymous Role (0 turns it off)

Both count over the same rolling window: Window in the dialog, anonymousConfig.sessionsPerDeviceWindowMs over the API (1 hour by default). The browser is identified by an id the widget keeps in the browser’s storage. The network is the client IP, so visitors behind one office or mobile-carrier address share its 60.

A limit applies only to starting a chat. A visitor who is over it keeps the chats they already have, and their next chat can start as soon as one of their earlier starts is older than the window.

When DioscHub refuses to start a chat, the widget does not lose the visitor’s message:

  • A line at the top of the chat says why, in plain words.
  • The message goes back into the composer (with any files attached to it), so the visitor can send it again with Enter. Each send tries to start the chat again.
  • The line goes away once a chat starts, or once the wait DioscHub gave has passed.
CodeWhyWhat the visitor sees
RATE_LIMITED (scope: 'ip')The network’s new-chat limit is reached.Too many new chats from this network. Try again in about 9 minutes.
RATE_LIMITED (scope: 'device')The browser’s new-chat limit is reached.Too many new chats from this browser. Try again in about 9 minutes.
CHALLENGE_FAILEDThe bot-protection (friction) challenge failed.We couldn’t verify this browser. Reload the page and try again.
AUTH_REQUIREDThe Assistant does not allow anonymous chats, and the visitor is not signed in.Sign in to chat with this assistant.
ASSISTANT_INACTIVE, ANONYMOUS_NOT_CONFIGUREDThe Assistant is not active on the current plan, or anonymous mode is on without an active anonymous Role.This assistant isn’t available right now.
NOT_CONNECTEDThe widget is not connected to DioscHub.Not connected. Check your connection and try again.
Anything else (including START_TIMEOUT, no answer in 5 seconds)Couldn’t start a chat right now. Please try again later.

The wait is rounded up to the minute: in a minute under one minute, in about N minutes below an hour, in about an hour (or about N hours) beyond. With no wait from DioscHub the sentence ends Try again later. The visitor never sees the code or DioscHub’s own error text.

To react on your page (log it, or offer sign-in), subscribe to session:start_refused:

diosc('on', 'session:start_refused', ({ code, message, retryAfterMs, scope }) => {
// message is the sentence the widget shows; retryAfterMs and scope come with RATE_LIMITED
console.info('chat not started', code, retryAfterMs);
});

A diosc('invoke', …) whose chat is refused still resolves; the event is how your page learns of it. An AUTH_REQUIRED refusal also fires auth:failed, as before.

When the visitor signs in, re-bind the same connection with a real identity. DioscHub recognizes that the connection’s session is anonymous and promotes it rather than starting a new one:

  • The conversation continues on the same session id — the message history is intact.
  • The session’s owner becomes the signed-in user (identity.userId).
  • The Assistant’s tool scope is re-resolved to the user’s Role, so the promoted session gets the signed-in user’s tools and features — not the anonymous set it started with.
  • The widget receives a fresh session token and continues without reloading the conversation.
  • Any files the visitor uploaded move into the signed-in user’s library (see Anonymous file upload).

To trigger this from the frontend after your app completes sign-in, call diosc('reauth'). The widget re-runs the bind on its live connection; your bind endpoint now sees an authenticated user and passes a real identity, and DioscHub promotes the session.

  1. Page loads, widget connects, your bind endpoint returns an anonymous bind (identity: null). (On a page with no bind endpoint, DioscHub makes this anonymous binding itself; see Anonymous-only embeds.)
  2. The visitor chats; the Assistant runs with the anonymous Role’s tools and features.
  3. The visitor signs in through your app.
  4. Your app calls diosc('reauth'); the widget re-binds with the signed-in user’s identity.
  5. DioscHub promotes the session in place; the same conversation continues, now as the signed-in user with their Role’s tools.

By default an anonymous visitor cannot upload files. For a helper or support assistant where visitors attach evidence — a screenshot, a log — you can allow it per Assistant: turn on the Files feature of the Assistant’s anonymous Role (role dialog → Features). It needs the Assistant’s anonymousMode enabled, an active anonymous Role, and a license that includes file handling.

An anonymous binding gets no REST token. Instead, when the Files switch is on, the session acknowledgement the widget receives on start (and on resume, restore or load) carries a short-lived files token scoped to that one session; with the switch off it carries none and the widget hides the upload control and the Files dialog. You never handle this token: the widget uses it only for its own file calls, and it never reaches the model, the logs or the session record.

  • It is accepted only on the chat-file routes — upload, list, name check, get, download, rename, delete and the upload policy. File generation and every other API refuse it.
  • It lives at most 24 hours from the session’s creation, and it is re-checked on every request against the live session and the license. Promoting the session, or turning off the Assistant’s anonymous mode, stops it on the next request (401). The token is refused (401) on every chat-file route as soon as the session has ended: completed, expired, deleted or quarantined, or its row is gone. An expired (idle) session that its visitor comes back to is active again, and so is its token, within the 24 hours.
  • The Files switch takes effect for new sessions. A session keeps the setting it started with, so turning Files off does not refuse a session that began with it on. To stop an existing anonymous session’s file access at once, end, delete or quarantine that session; the token is refused (401) immediately.
  • MCP file access and the generate_file and bundle_files tools stay refused for anonymous sessions, with or without the switch. The assistant’s file_search and read_file tools work on the visitor’s own current session files only, never another session’s and never a user library.

An anonymous visitor’s files live with their session, not in a user library. They are listed, read and changed only through that session: another session — even another session of the same visitor — gets 404 for them, as for a file that does not exist, and an upload naming a different session is refused with 403.

The Anonymous section of the anonymous Role’s dialog has a File uploads group with two caps:

FieldDefaultRange
Max files per session101 to 1000
Max MB per session25 MB1 to 1024 MB

Empty uses the default. Over the admin API they are anonymousConfig.filesMaxPerSession and anonymousConfig.filesMaxBytesPerSession (bytes) on the Role; they travel with the Assistant in a configuration transfer and are clamped to these ranges on import.

The caps act as the session’s storage quota: the effective quota is the smaller of the cap and any storage quota the anonymous Role (or the system) sets. An upload past it is refused with 413 QUOTA_EXCEEDED, and the upload size limit still applies to each file. Uploads also count against the deployment’s upload rate limit (by default 10 per minute and 100 per hour per client), and a files token is only issued after the session start has passed the bot-protection (friction) challenge and the anonymous session limits.

Expiry: 24 hours or the end of the session

Section titled “Expiry: 24 hours or the end of the session”

An anonymous file is kept until 24 hours after the session was created or the end of the session, whichever comes first. If the Role’s or the system’s retention is shorter, that applies instead.

  • A deleted session’s files are deleted at once.
  • A session that ends otherwise — it expires, is completed or is quarantined — has its files deleted by the next hourly retention sweep.
  • An upload into a session that has already ended is refused with 401, like every other call with its token. An upload already in flight when the session ends or is promoted is refused with 403 and code: "ANON_SESSION_ENDED"; nothing is stored.

On promotion, files move to the user’s library

Section titled “On promotion, files move to the user’s library”

When the visitor signs in and the session is promoted, the session’s files move into the signed-in user’s library on that Assistant:

  • A name that clashes with a file the user already has gets the next free name (report (2).pdf); nothing is overwritten.
  • The files count against the user’s storage quota from then on. If the move takes the user over their quota, every file still moves and nothing is evicted; the user’s next upload is refused until they free space.
  • The 24-hour anonymous expiry no longer applies. Each file’s expiry is re-stamped from the user’s retention, counted from the move (none when retention is off).
  • The anonymous files token stops working; the widget reaches the files with the user’s REST token.

Erasing an anonymous session through data erasure also erases the files held by that session — their stored bytes, search index, permissions, derived files and records — and the verification pass reports any that remain. A signed-in user’s library files are not touched by a session erasure; erasing the user removes those.


Next: return to MCP server development to expose the tools a signed-in user can now reach, or configure Roles and Assistants in the admin portal.