Skip to content

Frontend integration

DioscHub ships its chat as a single web component, <diosc-chat>. You load it onto a page, place it where you want, and control it from your app with one global function: diosc(). The widget code is served from your DioscHub instance at runtime. You embed a small loader, not the whole bundle.

The DioscHub chat widget open on a storefront page — a floating panel with the assistant's name, avatar, and greeting, docked in the bottom-right corner of the host site.

The <diosc-chat> widget embedded on a host page. It renders as a floating launcher that opens into this panel; you place and control it from your own app.

Pick the path that matches how your frontend is built.

Paste the loader script. It mounts <diosc-chat> for you and resolves everything else from your embed key server-side. You don’t pass an assistant ID or a backend URL.

<script src="https://your-hub.example.com/api/embed/YOUR_EMBED_KEY/loader.js"></script>

That’s the whole integration for a static page.

Once loaded, diosc() is how your app talks to the widget. You pass a command name and its arguments.

diosc('open'); // expand the widget
diosc('close'); // collapse it to the launcher
diosc('toggle'); // flip between the two

To react to what happens inside the widget, subscribe to its events:

diosc('on', 'session:upgraded', (session) => {
// the anonymous visitor just signed in, so refresh your UI
});

diosc('onAny', handler) receives every event if you’d rather route them yourself. The full event catalogue lives in the Web component API reference.

The widget has a built-in history UI — past conversations, rename, pin, and new-chat — gated by the sessionHistory and multipleSessions Role features (see Assistants & Roles). When those features are granted the visitor’s role, the history panel appears with no work on your part.

When the deployment’s retention window is on, and session history is licensed (Pro or Enterprise) and granted, the history panel marks a conversation that will be deleted within 7 days with “Deleted in N days. Pin to keep.”, and the pin button’s tooltip says whether pinned conversations are kept. Each session in the list carries expiresAt (an ISO date, or null when it won’t be deleted), and the list carries the retention in force (windowDays, keepPinned, pinnedLimitDays), on both the session:list event and the REST list, if you build your own history UI. A conversation deleted while it is open answers the next message with SESSION_NOT_FOUND.

If you want to drive sessions from your own UI instead, diosc() exposes the same operations: startNewSession, loadSession(id), renameSession(id, name), pinSession(id, isPinned), fetchSessionList / fetchSessionListViaREST (returns the list via the session:list event), and searchSessions({ query }) / clearSessionSearch. Every command and its arguments are in the client command API reference.

When the visitor’s Role has the files feature, the widget shows an upload control and a Files dialog with the user’s file library. You don’t configure upload limits in the widget: it reads them from the hub (GET /api/files/policy) and enforces them on every way a file reaches it — the file picker, drag and drop, paste, and files your client-side tools return. The limits themselves are set by an administrator; see File storage limits, quota & retention.

The widget checks a file against the hub’s policy before sending any bytes, and the hub checks again. When either refuses, the widget tells the user itself:

RefusalCodeWhat the user sees
The file is over the upload limitFILE_TOO_LARGEA toast naming the file and the limit, e.g. “report.pdf is larger than the 100 MB upload limit”.
The user’s storage quota is fullQUOTA_EXCEEDEDA toast such as “Storage full: 5.5 MB of 6 MB used” (or “Storage full: 20 of 20 files used”), and the Files dialog opens sorted largest first, showing each file’s size, search index and derived files so the user can free space.
The file is an executable (hub only, 415)FILE_TYPE_REFUSEDThe upload is marked failed. There is no dedicated message, and uploadError carries no code for it.

The file picker offers the types the hub lists (acceptedTypes in the policy), so there is no type list to maintain in your page. It is only a hint for the picker: drag and drop, paste and client-side tool files are not filtered, and the hub accepts any file that is not an executable, storing types it can’t read without indexing them. To offer your own list, set accept on the <diosc-file-upload> element; when set, it replaces the hub’s. See File types, kinds & parser limits.

There is no diosc('on') event for the refusals above — the widget handles them. (quota:exceeded is the token-budget event, not storage.) Where the refusal reaches your own code, it keeps its code and figures:

  • A client-side tool that returns a file gets { success: false, error, code: 'FILE_TOO_LARGE', limitBytes } or { success: false, error, code: 'QUOTA_EXCEEDED', usageBytes, quotaBytes, usageFiles, quotaFiles } when delivery is refused.
  • The uploadError DOM event of the widget’s upload element bubbles out of the widget with { fileId, error, code?, fileName?, limitBytes? } for a size refusal, or usageBytes, quotaBytes, usageFiles, quotaFiles and sizeBytes for a quota refusal.

When file retention is on, the Files dialog shows “Expires in N days” on each file that will expire. Anonymous visitors get the upload control only when the Assistant allows anonymous file upload.

After an upload, the hub indexes the file in the background, and every file reports its status. The Files dialog shows it on each row with no work on your part:

  • one badge per state: Indexing, Ready, Search unavailable, No text, Stored only or Failed;
  • the reason’s message, for example “Not searchable: the library is over its storage quota.”;
  • the warnings, as a count with each code and location, for example “1 warning: page_unreadable (page 14)”;
  • the step and a percent while the file is being indexed, for example “Indexing 33%” (or “Retrying 40%”);
  • a Re-index button on Failed and Search unavailable rows. While the Re-index limit is spent it says how long to wait.

Rows update live: the hub pushes files:status each time a file’s status or progress changes, to every widget the user has open on that Assistant. Your own code can subscribe to the same event:

diosc('on', 'files:status', (file) => {
// { fileId, filename, mimeType, status, reason, warnings, progress, canRead, canSearch, isIndexed }
if (!file.canSearch && file.status !== 'processing') flagFile(file.fileId, file.reason?.message);
});

files:updated still fires, with { fileId, filename }, to the session that uploaded a file once that file is indexed. The fields, the reasons, Re-index and the event are covered in full in Chat files & indexing.

The widget carries no credentials. It never asks the user to authenticate, and you never pass a token to diosc(). Instead, your backend hands DioscHub a scoped session for the already-signed-in user, and DioscHub forwards that opaquely to your MCP servers. It’s never placed in the model’s context. That binding is host-side and is covered in Identity & auth.

The defaults work out of the box. When you’re ready to tailor the experience, each of these is a self-contained how-to:


Next: expose one of your own endpoints to the assistant in MCP server development.